flashgate 0.4.0__tar.gz → 0.4.2__tar.gz

{flashgate-0.4.0 → flashgate-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.4.0
+Version: 0.4.2
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Requires-Python: >=3.11
@@ -79,8 +79,8 @@ fresh clone verifies out of the box once wired up.
 | 2 | flash failed |
 | 3 | board stayed silent (no banner / no signature within timeout) |
 | 4 | error string seen on serial (HardFault, assertion) |
-| 5 | on-board identity ≠ repo state |
-| 6 | environment error (no ST-Link / serial / tools) |
+| 5 | on-board identity ≠ repo state (git sha or board name) |
+| 6 | environment error (no ST-Link / serial / tools) — including probes explicitly required via `--probe`/`--all-probes` but the console UART is unavailable: a check that cannot run never counts as a pass |
 | 7 | functional probe failed |
 
 ## The Stop hook

{flashgate-0.4.0 → flashgate-0.4.2}/README.md

@@ -63,8 +63,8 @@ fresh clone verifies out of the box once wired up.
 | 2 | flash failed |
 | 3 | board stayed silent (no banner / no signature within timeout) |
 | 4 | error string seen on serial (HardFault, assertion) |
-| 5 | on-board identity ≠ repo state |
-| 6 | environment error (no ST-Link / serial / tools) |
+| 5 | on-board identity ≠ repo state (git sha or board name) |
+| 6 | environment error (no ST-Link / serial / tools) — including probes explicitly required via `--probe`/`--all-probes` but the console UART is unavailable: a check that cannot run never counts as a pass |
 | 7 | functional probe failed |
 
 ## The Stop hook

flashgate-0.4.2/flashgate/__init__.py

@@ -0,0 +1,13 @@
+"""flashgate: hardware-in-the-loop verification gate for coding agents.
+
+The agent may not claim firmware work is done until the board itself
+says so: build -> flash -> boot banner over serial, with exit codes
+that an agent harness (Stop hook) can enforce.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("flashgate")   # pyproject.toml is the single source
+except PackageNotFoundError:                  # running from a raw source tree
+    __version__ = "0.0.0"

{flashgate-0.4.0 → flashgate-0.4.2}/flashgate/cli.py

@@ -260,8 +260,10 @@ def cmd_verify(board: Board, probe_names: list[str] | None, evidence: str | None
 
 def _verify_swd(board: Board, probe_names: list[str] | None) -> int:
     """Boot gate through the ST-Link alone: fixed-address RAM signature.
-    No serial cable needed; functional probes are skipped (they need the
-    console) unless a probe run is explicitly requested and a port exists."""
+    No serial cable needed. Probes explicitly requested via --probe /
+    --all-probes (as the Stop hook does) MUST run: if the console is
+    missing or unusable, verify FAILS (exit 6) — a check that didn't
+    happen must never count as a pass."""
     print(_cyan(f"[verify] {board.name}: build -> flash -> SWD signature"))
     rc = _build(board)
     if rc != EXIT_OK:
@@ -287,6 +289,9 @@ def _verify_swd(board: Board, probe_names: list[str] | None) -> int:
         board.flash_connect, board.sig_address, board.sig_size,
         timeout_s=board.banner_timeout_s)
     if info is None:
+        if "not supported" in err:
+            print(_red(f"[verify] SIGNATURE LAYOUT MISMATCH: {err}"))
+            return EXIT_ENV
         print(_red(f"[verify] TIMEOUT: board never published its SWD signature ({err})"))
         return EXIT_BANNER_TIMEOUT
 
@@ -300,26 +305,46 @@ def _verify_swd(board: Board, probe_names: list[str] | None) -> int:
         return EXIT_SHA_MISMATCH
 
     if probe_names is not None:
-        port, _ = _console_port(board)
+        port, why = _console_port(board)
         if port is None:
-            print(_yellow("[verify] probes skipped: no console serial in swd mode"))
-        else:
-            try:
-                conn = serialmon.open_flush(port, board.baudrate)
-            except serial.SerialException as exc:
-                print(_yellow(f"[verify] probes skipped: cannot open {port} ({exc})"))
-                return EXIT_OK
-            try:
-                return _run_probes(board, None if probe_names == ["all"] else probe_names, conn)
-            finally:
-                conn.close()
-        return EXIT_OK
+            print(_red("[verify] probes were explicitly requested but no console serial "
+                       f"is available ({why}) — failing rather than passing unverified "
+                       "(drop --probe/--all-probes, or connect the console UART)"))
+            return EXIT_ENV
+        try:
+            conn = serialmon.open_flush(port, board.baudrate)
+        except serial.SerialException as exc:
+            print(_red(f"[verify] probes were explicitly requested but {port} cannot be "
+                       f"opened ({exc}) — failing rather than passing unverified"))
+            return EXIT_ENV
+        try:
+            return _run_probes(board, None if probe_names == ["all"] else probe_names, conn)
+        finally:
+            conn.close()
 
     print(_green(f"[verify] PASS — the board's RAM itself confirms the firmware booted "
                  f"(git={info['git']}), no serial cable involved"))
     return EXIT_OK
 
 
+def _check_banner_identity(board: Board, info: dict) -> int | None:
+    """Compare the banner's identity fields against the board profile.
+    Returns an exit code on contradiction, None when consistent."""
+    got_board = info.get("board")
+    if got_board and got_board != board.name:
+        print(_red(f"[verify] BOARD MISMATCH: banner says board={got_board}, "
+                   f"profile expects {board.name} — the verdict would not be "
+                   "about the board you configured"))
+        return EXIT_SHA_MISMATCH
+    expected = board.head_sha()
+    got = info.get("git")
+    if expected and got and expected != got:
+        print(_red(f"[verify] SHA MISMATCH: board runs {got}, repo HEAD is {expected} "
+                   "(rebuild after committing?)"))
+        return EXIT_SHA_MISMATCH
+    return None
+
+
 def _verify_uart(board: Board, probe_names: list[str] | None) -> int:
     all_probes = probe_names == ["all"]
     title = "[verify] {b}: build -> flash -> boot banner" + (" -> probes" if probe_names is not None else "")
@@ -365,12 +390,9 @@ def _verify_uart(board: Board, probe_names: list[str] | None) -> int:
         print(_green(f"[verify] banner OK: board={info.get('board')} git={info.get('git')} "
                      f"build={info.get('build')} rtos={info.get('rtos')}"))
 
-        expected = board.head_sha()
-        got = info.get("git")
-        if expected and got and expected != got:
-            print(_red(f"[verify] SHA MISMATCH: board runs {got}, repo HEAD is {expected} "
-                       "(rebuild after committing?)"))
-            return EXIT_SHA_MISMATCH
+        mismatch = _check_banner_identity(board, info)
+        if mismatch is not None:
+            return mismatch
 
         if probe_names is not None:
             return _run_probes(board, None if all_probes else probe_names, conn)

{flashgate-0.4.0 → flashgate-0.4.2}/flashgate/swdsig.py

@@ -18,6 +18,7 @@ from .flasher import FLASH_ATTEMPTS  # reuse attempt count semantics
 from .sttools import augmented_env, find_cubeprogrammer
 
 SIG_MAGIC = 0xF1A5C0DE
+SIG_VERSION = 1                 # the only signature layout this tool decodes
 READ_TIMEOUT_S = 30
 
 
@@ -25,6 +26,13 @@ class SwdError(Exception):
     pass
 
 
+class SignatureLayoutError(SwdError):
+    """CRC-valid signature whose layout version this tool cannot decode.
+
+    Waiting longer cannot fix a firmware/tool generation mismatch, so
+    callers should fail fast instead of polling to the timeout."""
+
+
 def read_ram(connect: str, address: int, size: int) -> bytes | None:
     """One CubeProgrammer memory read (HotPlug: does not halt the core)."""
     cli = find_cubeprogrammer()
@@ -49,7 +57,11 @@ def read_ram(connect: str, address: int, size: int) -> bytes | None:
 
 
 def parse_signature(buf: bytes) -> dict | None:
-    """Validate magic + CRC and decode the identity. None = not (yet) valid."""
+    """Validate magic, layout version and CRC; decode the identity.
+
+    None = not (yet) valid (retry). SignatureLayoutError = a complete,
+    CRC-valid signature from a layout generation this tool refuses to
+    interpret — treating it as evidence would be a lie."""
     if len(buf) < 64:
         return None
     magic, version, flags = struct.unpack_from("<IHH", buf, 0)
@@ -58,6 +70,11 @@ def parse_signature(buf: bytes) -> dict | None:
     crc_field = struct.unpack_from("<I", buf, 0x30)[0]
     if zlib.crc32(buf[:0x30]) & 0xFFFFFFFF != crc_field:
         return None                       # raced the boot-time write: retry
+    if version != SIG_VERSION:
+        raise SignatureLayoutError(
+            f"signature layout version {version} not supported "
+            f"(this tool decodes version {SIG_VERSION} only — "
+            "update flashgate or the firmware's bsp_signature)")
     git = buf[0x08:0x18].split(b"\x00", 1)[0].decode("ascii", errors="replace")
     build = buf[0x18:0x30].split(b"\x00", 1)[0].decode("ascii", errors="replace")
     return {"version": version, "flags": flags, "git": git, "build": build}
@@ -66,7 +83,11 @@ def parse_signature(buf: bytes) -> dict | None:
 def wait_for_signature(
     connect: str, address: int, size: int = 64, timeout_s: float = 15.0
 ) -> tuple[dict | None, str]:
-    """Poll the signature until valid or timeout. Returns (info, last_error)."""
+    """Poll the signature until valid or timeout. Returns (info, last_error).
+
+    A SignatureLayoutError aborts the poll immediately (returned as
+    (None, message)): an alien layout version is a permanent firmware/tool
+    mismatch, not something retrying can resolve."""
     deadline = time.monotonic() + timeout_s
     last = "no valid signature yet"
     while time.monotonic() < deadline:
@@ -76,7 +97,10 @@ def wait_for_signature(
             last = str(exc)
             time.sleep(1.0)
             continue
-        info = parse_signature(buf or b"")
+        try:
+            info = parse_signature(buf or b"")
+        except SignatureLayoutError as exc:
+            return None, str(exc)
         if info is not None:
             return info, ""
         time.sleep(0.5)

{flashgate-0.4.0 → flashgate-0.4.2}/flashgate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.4.0
+Version: 0.4.2
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Requires-Python: >=3.11
@@ -79,8 +79,8 @@ fresh clone verifies out of the box once wired up.
 | 2 | flash failed |
 | 3 | board stayed silent (no banner / no signature within timeout) |
 | 4 | error string seen on serial (HardFault, assertion) |
-| 5 | on-board identity ≠ repo state |
-| 6 | environment error (no ST-Link / serial / tools) |
+| 5 | on-board identity ≠ repo state (git sha or board name) |
+| 6 | environment error (no ST-Link / serial / tools) — including probes explicitly required via `--probe`/`--all-probes` but the console UART is unavailable: a check that cannot run never counts as a pass |
 | 7 | functional probe failed |
 
 ## The Stop hook

{flashgate-0.4.0 → flashgate-0.4.2}/flashgate.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ flashgate.egg-info/entry_points.txt
 flashgate.egg-info/requires.txt
 flashgate.egg-info/top_level.txt
 tests/test_board.py
+tests/test_cli.py
 tests/test_gatestate.py
 tests/test_probes.py
 tests/test_swdsig.py

{flashgate-0.4.0 → flashgate-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashgate"
-version = "0.4.0"
+version = "0.4.2"
 description = "Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so."
 readme = "README.md"
 requires-python = ">=3.11"

flashgate-0.4.2/tests/test_cli.py

@@ -0,0 +1,148 @@
+"""cli-level fail-closed guards: a check that cannot run must fail, never pass.
+
+Regression coverage for the false-green found in 0.4.1: --all-probes with
+no console serial in swd mode used to print a yellow "skipped" and return 0.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+import serial
+
+from flashgate import cli
+from flashgate.board import Board, load_board
+
+
+BODY = """
+board: test-board
+mcu: STM32F999
+description: unit test fixture
+firmware:
+  dir: fw
+  build: ninja -C build
+  artifact: build/fw.bin
+serial:
+  baudrate: 9600
+  banner: 'BOOT board={board} git={git}'
+"""
+
+
+def make_board(tmp_path) -> Board:
+    fw = tmp_path / "fw"
+    fw.mkdir(exist_ok=True)
+    p = tmp_path / "board.yaml"
+    p.write_text(BODY, encoding="utf-8")
+    return load_board(p)
+
+
+@pytest.fixture
+def happy_swd(monkeypatch):
+    """Everything up to (but excluding) the probe stage succeeds: build,
+    flash, wipe, start, and a valid v1 signature answers immediately."""
+    monkeypatch.setattr(cli, "_build", lambda board: cli.EXIT_OK)
+    monkeypatch.setattr(cli.flasher, "flash",
+                        lambda *a, **k: SimpleNamespace(ok=True, detail=""))
+    monkeypatch.setattr(cli.flasher, "write32", lambda *a, **k: True)
+    monkeypatch.setattr(cli.flasher, "start_app", lambda *a, **k: True)
+    monkeypatch.setattr(cli.swdsig, "wait_for_signature",
+                        lambda *a, **k: ({"version": 1, "flags": 0,
+                                          "git": "x", "build": "y"}, ""))
+    monkeypatch.setattr(Board, "head_sha", lambda self: None)
+
+
+class TestSwdProbeGuard:
+    def test_probes_required_no_serial_fails(self, tmp_path, happy_swd, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli, "_console_port", lambda b: (None, "no serial found"))
+        assert cli._verify_swd(board, ["all"]) == cli.EXIT_ENV
+
+    def test_probes_required_port_unopenable_fails(self, tmp_path, happy_swd, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli, "_console_port", lambda b: ("COM3", "hint"))
+
+        def boom(*a, **k):
+            raise serial.SerialException("access denied")
+        monkeypatch.setattr(cli.serialmon, "open_flush", boom)
+        assert cli._verify_swd(board, ["all"]) == cli.EXIT_ENV
+
+    def test_probes_required_run_when_serial_ok(self, tmp_path, happy_swd, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli, "_console_port", lambda b: ("COM3", "hint"))
+        monkeypatch.setattr(cli.serialmon, "open_flush",
+                            lambda *a, **k: SimpleNamespace(close=lambda: None))
+        seen = {}
+        def run_probes(board, names, conn):
+            seen["names"] = names
+            return cli.EXIT_OK
+        monkeypatch.setattr(cli, "_run_probes", run_probes)
+        assert cli._verify_swd(board, ["all"]) == cli.EXIT_OK
+        assert seen["names"] is None                # "all" expanded, not literal
+
+    def test_no_probes_requested_still_passes_without_serial(self, tmp_path, happy_swd, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli, "_console_port", lambda b: (None, "no serial"))
+        assert cli._verify_swd(board, None) == cli.EXIT_OK
+
+
+class TestSignatureErrors:
+    def test_layout_mismatch_fails_fast_as_env_error(self, tmp_path, happy_swd, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(
+            cli.swdsig, "wait_for_signature",
+            lambda *a, **k: (None, "signature layout version 3 not supported "
+                                   "(this tool decodes version 1 only)"))
+        assert cli._verify_swd(board, None) == cli.EXIT_ENV
+
+    def test_plain_timeout_still_exit_3(self, tmp_path, happy_swd, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli.swdsig, "wait_for_signature",
+                            lambda *a, **k: (None, "no valid signature yet"))
+        assert cli._verify_swd(board, None) == cli.EXIT_BANNER_TIMEOUT
+
+
+class TestBannerIdentity:
+    def test_board_mismatch_detected(self, tmp_path, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(Board, "head_sha", lambda self: None)
+        rc = cli._check_banner_identity(board, {"board": "other-board", "git": "x"})
+        assert rc == cli.EXIT_SHA_MISMATCH
+
+    def test_sha_mismatch_detected(self, tmp_path, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(Board, "head_sha", lambda self: "abc1234")
+        rc = cli._check_banner_identity(board, {"board": "test-board", "git": "deadbee"})
+        assert rc == cli.EXIT_SHA_MISMATCH
+
+    def test_consistent_identity_passes(self, tmp_path, monkeypatch):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(Board, "head_sha", lambda self: "abc1234")
+        assert cli._check_banner_identity(
+            board, {"board": "test-board", "git": "abc1234"}) is None
+
+
+class TestAutoRouting:
+    def test_auto_picks_swd_without_serial(self, tmp_path, monkeypatch):
+        board = make_board(tmp_path)
+        seen = {}
+        monkeypatch.setattr(cli, "_console_port", lambda b: (None, "none"))
+        def fake_swd(b, p):
+            seen["mode"] = "swd"; return cli.EXIT_OK
+        def fake_uart(b, p):
+            seen["mode"] = "uart"; return cli.EXIT_OK
+        monkeypatch.setattr(cli, "_verify_swd", fake_swd)
+        monkeypatch.setattr(cli, "_verify_uart", fake_uart)
+        assert cli.cmd_verify(board, None, None) == cli.EXIT_OK
+        assert seen["mode"] == "swd"
+
+    def test_auto_picks_uart_with_serial(self, tmp_path, monkeypatch):
+        board = make_board(tmp_path)
+        seen = {}
+        monkeypatch.setattr(cli, "_console_port", lambda b: ("COM3", "hint"))
+        def fake_swd(b, p):
+            seen["mode"] = "swd"; return cli.EXIT_OK
+        def fake_uart(b, p):
+            seen["mode"] = "uart"; return cli.EXIT_OK
+        monkeypatch.setattr(cli, "_verify_swd", fake_swd)
+        monkeypatch.setattr(cli, "_verify_uart", fake_uart)
+        assert cli.cmd_verify(board, None, None) == cli.EXIT_OK
+        assert seen["mode"] == "uart"

{flashgate-0.4.0 → flashgate-0.4.2}/tests/test_swdsig.py

@@ -3,13 +3,16 @@
 import struct
 import zlib
 
-from flashgate.swdsig import SIG_MAGIC, parse_signature
+import pytest
 
+from flashgate.swdsig import SIG_MAGIC, SignatureLayoutError, parse_signature
 
-def build_sig(git=b"abc1234", build=b"2026-08-31T08:00:00Z", magic=SIG_MAGIC) -> bytes:
+
+def build_sig(git=b"abc1234", build=b"2026-08-31T08:00:00Z", magic=SIG_MAGIC,
+              version=1) -> bytes:
     buf = bytearray(64)
     struct.pack_into("<I", buf, 0x00, magic)
-    struct.pack_into("<H", buf, 0x04, 1)
+    struct.pack_into("<H", buf, 0x04, version)
     struct.pack_into("<H", buf, 0x06, 1)
     buf[0x08:0x08 + len(git)] = git
     buf[0x18:0x18 + len(build)] = build
@@ -42,3 +45,19 @@ class TestParseSignature:
 
     def test_short_buffer_rejected(self):
         assert parse_signature(build_sig()[:48]) is None
+
+    def test_unknown_layout_version_rejected(self):
+        # CRC-valid, magic-valid — but a layout generation this tool
+        # refuses to decode must never be treated as evidence.
+        with pytest.raises(SignatureLayoutError, match="version 2"):
+            parse_signature(build_sig(version=2))
+
+    def test_wait_for_signature_fails_fast_on_unknown_version(self, monkeypatch):
+        # An alien layout is permanent: the poll must return immediately
+        # with the reason instead of spinning to the timeout.
+        from flashgate import swdsig
+
+        monkeypatch.setattr(swdsig, "read_ram", lambda *a, **k: build_sig(version=9))
+        info, err = swdsig.wait_for_signature("port=SWD", 0x2001FF00, 64, timeout_s=20)
+        assert info is None
+        assert "version 9 not supported" in err

flashgate-0.4.0/flashgate/__init__.py

@@ -1,8 +0,0 @@
-"""flashgate: hardware-in-the-loop verification gate for coding agents.
-
-The agent may not claim firmware work is done until the board itself
-says so: build -> flash -> boot banner over serial, with exit codes
-that an agent harness (Stop hook) can enforce.
-"""
-
-__version__ = "0.3.0"