firestarter 3.2.7b2__tar.gz → 3.2.7b3__tar.gz

{firestarter-3.2.7b2/firestarter.egg-info → firestarter-3.2.7b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firestarter
-Version: 3.2.7b2
+Version: 3.2.7b3
 Summary: EPROM programmer software for the Relatively Universal ROM Programmer
 Author-email: Henrik Olsson <henols@gmail.com>
 Project-URL: Homepage, https://github.com/henols/firestarter_app

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.2.7b2'
-__version_tuple__ = version_tuple = (3, 2, 7, 'b2')
+__version__ = version = '3.2.7b3'
+__version_tuple__ = version_tuple = (3, 2, 7, 'b3')
 
-__commit_id__ = commit_id = 'g30e9def'
+__commit_id__ = commit_id = 'g85b7152'

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter/channel.py

@@ -59,23 +59,16 @@ def is_prerelease_build() -> bool:
     """True when this build came off `beta` (its own version is a pre-release).
 
     Fails **closed**: an unparseable version is treated as stable, so a gated
-    feature stays hidden rather than leaking. This matches
-    `_maybe_auto_route_to_pre`, which also treats `InvalidVersion` as
-    not-a-prerelease. In practice `__version__` is a literal in the package and
-    is always valid PEP 440; dev versions (`2.0.7_dev`) parse as pre-releases and
-    therefore keep gated features enabled while working from a checkout.
+    feature stays hidden rather than leaking. `_maybe_auto_route_to_pre` uses
+    this function, so it treats an unparseable version the same way. In
+    practice `__version__` is a literal in the package and is always valid
+    PEP 440; dev versions (`2.0.7_dev`) parse as pre-releases and therefore
+    keep gated features enabled while working from a checkout.
     """
-    try:
-        from packaging.version import InvalidVersion, Version
+    import firestarter as _pkg
+    from firestarter.fw_release_gate import is_prerelease_version
 
-        import firestarter as _pkg
-
-        try:
-            return bool(Version(_pkg.__version__).is_prerelease)
-        except InvalidVersion:
-            return False
-    except ImportError:  # pragma: no cover — packaging is a hard dependency
-        return False
+    return is_prerelease_version(_pkg.__version__) is True
 
 
 def is_board_available(board: str | None) -> bool:

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter/cli_handlers.py

@@ -343,29 +343,15 @@ def _maybe_auto_route_to_pre(args: object) -> None:
         or getattr(args, "stable", False)
     ):
         return
-    try:
-        from packaging.version import InvalidVersion, Version
-
-        import firestarter as _pkg
-
-        try:
-            if Version(_pkg.__version__).is_prerelease:
-                args.pre = True  # type: ignore[attr-defined]
-                helper_logger.info(
-                    "Beta app detected — defaulting to --pre. "
-                    "Use --firmware-version X.Y.Z to pin a stable version."
-                )
-        except InvalidVersion:
-            # Deliberate fail-OPEN, and deliberately the opposite polarity to
-            # fw_release_gate, which fails CLOSED on the same unreadable input.
-            # The asymmetry is intended: the worst case here is that the wrong
-            # channel is picked, which the gate then judges on its merits; the
-            # worst case there is a board flashed with firmware this host cannot
-            # drive, recoverable only through the bootloader. Do not "align"
-            # these two without re-reading both worst cases.
-            pass
-    except ImportError:
-        pass
+    # An unreadable version is not a pre-release here: the worst case is the
+    # wrong channel, which fw_release_gate then judges and refuses (it fails
+    # CLOSED on the same input). Do not "align" the two polarities.
+    if is_prerelease_build():
+        args.pre = True  # type: ignore[attr-defined]
+        helper_logger.info(
+            "Beta app detected — defaulting to --pre. "
+            "Use --firmware-version X.Y.Z to pin a stable version."
+        )
 
 
 def _build_op_flags(

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter/eprom_operations.py

@@ -16,7 +16,7 @@ import statistics
 import time
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Callable, Dict, Tuple  # noqa: UP035
+from typing import BinaryIO, Callable, Dict, Tuple  # noqa: UP035
 
 import tqdm
 from tqdm.contrib.logging import logging_redirect_tqdm
@@ -362,18 +362,23 @@ def _blank_expected_bytes(_offset: int, length: int) -> bytes:
     return b"\xff" * length
 
 
-def _default_read_path(eprom_name: str) -> str:
-    """The output file name `read` uses when the user gives none:
+def _open_default_read_file(eprom_name: str) -> tuple[str, BinaryIO]:
+    """Create the output file `read` uses when the user gives none:
     `<NAME>.bin`, or `<NAME>-<n>.bin` with the lowest free `n` when that
     file exists, so a second read never overwrites the first.
+
+    Mode 'xb' claims the name and creates the file in one step, so two reads
+    that start together never get the same name.
     """
     base = eprom_name.upper()
     path = f"{base}.bin"
     n = 1
-    while os.path.exists(path):
-        path = f"{base}-{n}.bin"
-        n += 1
-    return path
+    while True:
+        try:
+            return path, open(path, "xb")
+        except FileExistsError:
+            path = f"{base}-{n}.bin"
+            n += 1
 
 
 def _write_blank_guard_refusal_message(
@@ -1312,14 +1317,20 @@ class EpromOperator:
             if not cmd_data:
                 return False
 
-            actual_output_file = output_file or _default_read_path(eprom_name)
-            logger.info(
-                f"Reading EPROM {eprom_name.upper()}, saving to {actual_output_file}"
-            )
-            start_time = time.time()
-
+            actual_output_file = output_file or ""
+            is_ok = False
             try:
-                with open(actual_output_file, "wb") as file_handle:
+                if output_file:
+                    file_handle = open(output_file, "wb")
+                else:
+                    actual_output_file, file_handle = _open_default_read_file(
+                        eprom_name
+                    )
+                logger.info(
+                    f"Reading EPROM {eprom_name.upper()}, saving to {actual_output_file}"
+                )
+                start_time = time.time()
+                with file_handle:
 
                     def _write_to_file(address, data_chunk):
                         file_handle.seek(address)
@@ -1340,6 +1351,14 @@ class EpromOperator:
             except IOError as e:  # noqa: UP024
                 logger.error(f"File I/O error with {actual_output_file}: {e}")
                 return False
+            finally:
+                # A failed read with a generated name leaves no file behind,
+                # so the next read takes that name again.
+                if not output_file and actual_output_file and not is_ok:
+                    try:
+                        os.remove(actual_output_file)
+                    except OSError:
+                        pass
 
     def consistency_check_eprom(
         self,

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter/firmware.py

@@ -39,7 +39,12 @@ from firestarter.exceptions import (
     ProgrammerNotFoundError,
     SerialError,
 )
-from firestarter.fw_release_gate import require_installable_release
+from firestarter.fw_release_gate import (
+    feature_version,
+    is_prerelease_version,
+    matches_stable_cli,
+    require_installable_release,
+)
 from firestarter.serial_comm import SerialCommunicator
 from firestarter.timestamps import iso_text_to_cet
 
@@ -331,15 +336,21 @@ class FirmwareManager:
         channel: Literal["stable", "pre", "pinned"] = "stable",
         version: str | None = None,
         board: str = "uno",
+        app_version: str | None = None,
     ) -> Tuple[str | None, str | None]:  # noqa: UP006
         """Router: returns (resolved_version, download_url) or (None, None) on failure.
 
-        channel='stable'  → delegates to fetch_latest_release_info (back-compat shim).
+        channel='stable'  → for a stable app_version, the highest stable release on
+                            its feature version (a stable CLI 3.2.x runs 3.2.y only);
+                            otherwise delegates to fetch_latest_release_info.
         channel='pre'     → paginates /releases, takes the highest non-draft release by
                             PEP 440, stable or pre-release; falls back to stable if none.
         channel='pinned'  → fetches /releases/tags/{version} directly.
         """  # noqa: E501
         if channel == "stable":
+            app_feature = feature_version(app_version)
+            if is_prerelease_version(app_version) is False and app_feature:
+                return self._fetch_matching_stable_release_info(app_feature, board)
             return self.fetch_latest_release_info(board=board)
 
         elif channel == "pinned":
@@ -413,6 +424,44 @@ class FirmwareManager:
             )
             return None, None
 
+    def _fetch_matching_stable_release_info(
+        self, app_feature: tuple[int, int], board: str
+    ) -> Tuple[str | None, str | None]:  # noqa: UP006
+        """The highest non-draft stable release whose feature version is app_feature."""
+        line = f"{app_feature[0]}.{app_feature[1]}.x"
+        try:
+            all_releases = self._fetch_all_releases()
+        except requests.RequestException as e:
+            logger.error(f"Failed to fetch firmware releases: {e}")
+            return None, None
+
+        candidates = []
+        for r in all_releases:
+            if r.get("draft"):
+                continue
+            try:
+                tag_version = Version(r.get("tag_name", ""))
+            except InvalidVersion:
+                continue
+            if tag_version.is_prerelease:
+                continue
+            if (tag_version.major, tag_version.minor) == app_feature:
+                candidates.append((tag_version, r))
+
+        if not candidates:
+            logger.error(f"No stable firmware release {line} was found.")
+            return None, None
+
+        _, picked = max(candidates, key=lambda t: t[0])
+        download_url = _pick_asset(picked.get("assets", []), board)
+        if not download_url:
+            logger.error(
+                f"Release {picked.get('tag_name')!r} has no asset "
+                f"{_asset_label(board)} for board {board!r}."
+            )
+            return None, None
+        return picked.get("tag_name"), download_url
+
     def list_releases(
         self,
         channel_filter: Literal["all", "pre", "stable"] = "all",
@@ -847,8 +896,17 @@ class FirmwareManager:
             self._hint_dfu_board()
             return False
 
+        if app_version is None:
+            # Dereferenced at call time, not bound at import, so a test can
+            # monkeypatch firestarter.__version__ without reloading this module.
+            import firestarter as _pkg
+
+            app_version = _pkg.__version__
         latest_version, download_url = self.fetch_release_info(
-            channel=channel, version=pinned_version, board=board_to_use
+            channel=channel,
+            version=pinned_version,
+            board=board_to_use,
+            app_version=app_version,
         )
 
         # Guard the release tag where it is BORN, not on each branch that
@@ -869,12 +927,6 @@ class FirmwareManager:
         #
         # The same call refuses a pre-release on a stable CLI. That covers a
         # library caller that asks a stable CLI for channel="pre".
-        if app_version is None:
-            # Dereferenced at call time, not bound at import, so a test can
-            # monkeypatch firestarter.__version__ without reloading this module.
-            import firestarter as _pkg
-
-            app_version = _pkg.__version__
         require_installable_release(
             app_version,
             latest_version,
@@ -920,8 +972,22 @@ class FirmwareManager:
                     "only guard."
                 )
 
+        # A stable CLI runs a stable release on its own feature version only. A
+        # board on anything else is never up to date, even when its version is
+        # higher: a stable 3.2.6 CLI moves a 3.2.3b1 board to 3.2.2.
+        mismatched = bool(
+            current_version
+            and is_prerelease_version(app_version) is False
+            and not matches_stable_cli(app_version, current_version)
+        )
         is_up_to_date = False
-        if current_version and latest_version:
+        if mismatched:
+            logger.warning(
+                f"Firmware {current_version} does not match CLI {app_version}. "
+                "A stable CLI uses a stable firmware release with the same "
+                "major.minor version."
+            )
+        elif current_version and latest_version:
             is_up_to_date = self._compare_versions(current_version, latest_version)
 
         if is_up_to_date and not force_install:
@@ -949,10 +1015,12 @@ class FirmwareManager:
         elif (
             not is_up_to_date and current_version and latest_version
         ):  # No flags, but update available
-            if Confirm.ask(
-                f"New firmware {latest_version} available for {board_to_use} (current: {current_version}). Update now?",  # noqa: E501
-                default=False,
-            ):
+            prompt = (
+                f"Install firmware {latest_version} for {board_to_use} (current: {current_version})?"  # noqa: E501
+                if mismatched
+                else f"New firmware {latest_version} available for {board_to_use} (current: {current_version}). Update now?"  # noqa: E501
+            )
+            if Confirm.ask(prompt, default=False):
                 should_install_now = True
             else:
                 logger.info("Firmware update cancelled by user.")

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter/fw_release_gate.py

@@ -21,6 +21,11 @@ PEP 440 release; a pre-release firmware is a b/rc/dev tag. This rule ignores the
 feature version, and nothing waives it: a stable user gets stable firmware only.
 A pre-release CLI (a b/rc tag, or a dev checkout) installs either.
 
+A stable CLI also refuses a release BELOW its feature version. A stable CLI
+3.2.x runs stable firmware 3.2.y only (`matches_stable_cli`). Nothing waives
+this refusal either. `firmware.fetch_release_info` picks the highest matching
+stable release for a stable CLI, so `fw --install` installs a matching release.
+
 The reverse pairing -- a CLI newer than the firmware -- is NOT gated here.
 `_maybe_auto_route_to_pre` in cli_handlers.py steers channel selection away from
 it. The two checks cover opposite directions and neither replaces the other.
@@ -37,7 +42,7 @@ the failed fetch. Turning a GitHub outage into a version-mismatch refusal would
 be a lie. This is the one place the gate looks fail-open and is not.
 
 Escape for the feature-version refusal: `--allow-newer-firmware`. Never an
-environment variable. The pre-release refusal has no escape.
+environment variable. The pre-release and older-line refusals have no escape.
 
 Unlike the pre-serial gates, the authoritative call runs AFTER the release
 metadata fetch, because the release tag is only known then. It still runs before
@@ -90,6 +95,14 @@ _PRERELEASE_ON_STABLE_FORMAT = (
     "Run 'pip install --upgrade --pre firestarter'."
 )
 
+_OLDER_LINE_ON_STABLE_FORMAT = (
+    "Firmware {release} is feature version {release_feature}. This CLI is {app}, "
+    "a stable release. A stable CLI installs stable firmware {app_feature}.x only. "
+    "Refusing to install firmware {release}.\n"
+    "Run 'firestarter fw --install' to install the latest stable firmware "
+    "{app_feature}.x."
+)
+
 _UNREADABLE_TEXT = "an unreadable version"
 
 
@@ -123,6 +136,17 @@ def is_prerelease_version(raw: str | None) -> bool | None:
         return None
 
 
+def matches_stable_cli(app_version: str | None, fw_version: str | None) -> bool:
+    """True when fw_version is a stable release on app_version's feature version.
+
+    The firmware a stable CLI runs. False when either version cannot be read.
+    """
+    if is_prerelease_version(fw_version) is not False:
+        return False
+    app = feature_version(app_version)
+    return app is not None and feature_version(fw_version) == app
+
+
 def is_refused(app_version: str | None, release_version: str | None) -> bool:
     """True when this CLI must not flash this release.
 
@@ -148,20 +172,30 @@ def require_installable_release(
 
     Returns None on pass. `allow_newer` waives the feature-version refusal; it
     defaults to False so a library caller that does not ask for the waiver does
-    not get it. Nothing waives the pre-release refusal on a stable CLI.
+    not get it. Nothing waives the pre-release or older-line refusal on a
+    stable CLI.
 
-    An unreadable version on either side is not judged by the pre-release rule.
+    An unreadable version on either side is not judged by the stable-CLI rules.
     The feature-version check refuses it.
     """
-    if (
-        is_prerelease_version(app_version) is False
-        and is_prerelease_version(release_version) is True
-    ):
-        raise FirmwareReleaseRefusedError(
-            _PRERELEASE_ON_STABLE_FORMAT.format(
-                app=app_version, release=release_version
+    if is_prerelease_version(app_version) is False:
+        if is_prerelease_version(release_version) is True:
+            raise FirmwareReleaseRefusedError(
+                _PRERELEASE_ON_STABLE_FORMAT.format(
+                    app=app_version, release=release_version
+                )
+            )
+        app = feature_version(app_version)
+        release = feature_version(release_version)
+        if app and release and release < app:
+            raise FirmwareReleaseRefusedError(
+                _OLDER_LINE_ON_STABLE_FORMAT.format(
+                    app=app_version,
+                    release=release_version,
+                    app_feature=f"{app[0]}.{app[1]}",
+                    release_feature=f"{release[0]}.{release[1]}",
+                )
             )
-        )
     if allow_newer or not is_refused(app_version, release_version):
         return
     app = feature_version(app_version)

{firestarter-3.2.7b2 → firestarter-3.2.7b3/firestarter.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firestarter
-Version: 3.2.7b2
+Version: 3.2.7b3
 Summary: EPROM programmer software for the Relatively Universal ROM Programmer
 Author-email: Henrik Olsson <henols@gmail.com>
 Project-URL: Homepage, https://github.com/henols/firestarter_app

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/firestarter.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "3.2.7b2",
+  "tag": "3.2.7b3",
   "distance": 0,
-  "node": "g30e9def",
+  "node": "g85b7152",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-28"

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/tests/test_eprom_operations.py

@@ -17,14 +17,17 @@ Phase 44 Plan 03 additions (read_timing block):
     test_consistency_check_default_params_absent_from_command — no extra keys when 0
 """
 
+import contextlib
 import logging
 import tempfile
 from pathlib import Path
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
+
+import pytest
 
 from firestarter.compare import CompareAccumulator
 from firestarter.config import ConfigManager
-from firestarter.eprom_operations import EpromOperator, _default_read_path
+from firestarter.eprom_operations import EpromOperator, _open_default_read_file
 from firestarter.messages import (
     MSG_DATA_CHUNK,
     MSG_END_DONE,
@@ -2731,14 +2734,64 @@ def test_seen_message_ids_records_decoded_ids_and_stays_bounded(
     assert all(isinstance(i, int) for i in comm.seen_message_ids)
 
 
-def test_default_read_path_adds_lowest_free_suffix(tmp_path, monkeypatch):
+def test_default_read_file_takes_lowest_free_suffix(tmp_path, monkeypatch):
     """`read` with no file name never overwrites an earlier read: the
-    default `<NAME>.bin` gets `-1`, `-2`, ... when that name is taken."""
+    default `<NAME>.bin` gets `-1`, `-2`, ... when that name is taken.
+    Opening the file claims the name, so the next call skips it."""
     monkeypatch.chdir(tmp_path)
-    assert _default_read_path("w27c512") == "W27C512.bin"
+    names = []
+    for _ in range(3):
+        path, fh = _open_default_read_file("w27c512")
+        fh.close()
+        names.append(path)
+    assert names == ["W27C512.bin", "W27C512-1.bin", "W27C512-2.bin"]
+
+
+def _operator_reading(monkeypatch, outcome):
+    """An EpromOperator whose read writes 4 bytes, then returns or raises `outcome`."""
+    operator = EpromOperator(MagicMock())
+
+    @contextlib.contextmanager
+    def _context(*_args, **_kwargs):
+        yield {"address": 0, "memory-size": 4}, 512, "Read"
+
+    def _state_machine(_op_name, process_data_chunk_callback, **_kwargs):
+        process_data_chunk_callback(0, b"\x01\x02\x03\x04")
+        if isinstance(outcome, BaseException):
+            raise outcome
+        return outcome, None
+
+    monkeypatch.setattr(operator, "_operation_context", _context)
+    monkeypatch.setattr(operator, "_run_state_machine", _state_machine)
+    return operator
 
-    (tmp_path / "W27C512.bin").write_bytes(b"")
-    assert _default_read_path("w27c512") == "W27C512-1.bin"
 
-    (tmp_path / "W27C512-1.bin").write_bytes(b"")
-    assert _default_read_path("w27c512") == "W27C512-2.bin"
+def test_read_with_default_name_keeps_the_file(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert _operator_reading(monkeypatch, True).read_eprom("w27c512", {})
+    assert (tmp_path / "W27C512.bin").read_bytes() == b"\x01\x02\x03\x04"
+
+
+@pytest.mark.parametrize("outcome", [False, KeyboardInterrupt()])
+def test_failed_read_with_default_name_leaves_no_file(tmp_path, monkeypatch, outcome):
+    """A failed or interrupted read frees its name, so the next read takes it."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "W27C512.bin").write_bytes(b"earlier read")
+    operator = _operator_reading(monkeypatch, outcome)
+    if isinstance(outcome, BaseException):
+        with pytest.raises(KeyboardInterrupt):
+            operator.read_eprom("w27c512", {})
+    else:
+        assert operator.read_eprom("w27c512", {}) is False
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["W27C512.bin"]
+    assert (tmp_path / "W27C512.bin").read_bytes() == b"earlier read"
+
+
+def test_failed_read_with_named_file_keeps_it(tmp_path, monkeypatch):
+    """A file the user named is not removed: it is theirs."""
+    out = tmp_path / "mine.bin"
+    assert (
+        _operator_reading(monkeypatch, False).read_eprom("w27c512", {}, str(out))
+        is False
+    )
+    assert out.exists()

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/tests/test_firmware_install.py

@@ -1425,12 +1425,12 @@ class TestManageFirmwareUpdate:
         monkeypatch.setattr(
             fm,
             "fetch_release_info",
-            lambda channel="stable", version=None, board="uno": (
+            lambda channel="stable", version=None, board="uno", **_kw: (
                 "3.1.0",
                 "https://example.com/firestarter_uno.hex",
             ),
         )
-        result = fm.manage_firmware_update(install_flag=True)
+        result = fm.manage_firmware_update(install_flag=True, app_version="3.1.0")
         assert result is True
 
     def test_manage_no_current_no_install_intent_returns_false(self, monkeypatch):
@@ -1442,13 +1442,15 @@ class TestManageFirmwareUpdate:
         monkeypatch.setattr(
             fm,
             "fetch_release_info",
-            lambda channel="stable", version=None, board="uno": (
+            lambda channel="stable", version=None, board="uno", **_kw: (
                 "3.1.0",
                 "https://example.com/firestarter_uno.hex",
             ),
         )
         # install_flag=False + no FLAG_FORCE in flags=0 → returns False
-        result = fm.manage_firmware_update(install_flag=False, flags=0)
+        result = fm.manage_firmware_update(
+            install_flag=False, flags=0, app_version="3.1.0"
+        )
         assert result is False
 
 
@@ -1474,7 +1476,7 @@ class TestNewerFirmwareRefusal:
         monkeypatch.setattr(
             fm,
             "fetch_release_info",
-            lambda channel="stable", version=None, board="uno": (
+            lambda channel="stable", version=None, board="uno", **_kw: (
                 latest,
                 "https://example.com/firestarter_uno.hex" if latest else None,
             ),

{firestarter-3.2.7b2 → firestarter-3.2.7b3}/tests/test_fw_port_targeting_and_blind_install.py

@@ -220,7 +220,7 @@ def _manager_that_cannot_identify(monkeypatch):
     monkeypatch.setattr(
         fm,
         "fetch_release_info",
-        lambda channel="stable", version=None, board="uno": (
+        lambda channel="stable", version=None, board="uno", **_kw: (
             "3.0.0b19",
             f"https://example.invalid/{board}.hex",
         ),
@@ -318,7 +318,7 @@ class TestBlindInstallRequiresExplicitBoard:
         monkeypatch.setattr(
             fm,
             "fetch_release_info",
-            lambda channel="stable", version=None, board="uno": (
+            lambda channel="stable", version=None, board="uno", **_kw: (
                 "3.0.0b19",
                 f"https://example.invalid/{board}.hex",
             ),