flashgate 0.5.3__tar.gz → 0.5.4__tar.gz

{flashgate-0.5.3 → flashgate-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.5.3
+Version: 0.5.4
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Project-URL: Homepage, https://github.com/Lion-1209/flashgate
@@ -50,8 +50,9 @@ Both carry the git sha plus `-dirty` when the tree differs from HEAD, so a
 passing verify proves the board is running a build of your current HEAD
 (`-dirty` marks uncommitted changes; it does not fingerprint their
 content — the Stop hook's tree fingerprint covers that side: tracked diffs
-in full, untracked files by path + size + first 4 MiB. Files ignored by
-git and nested git repositories are outside the gate). Functional probes then send real commands and assert on the answers,
+in full, untracked files and the board profile by path + size + first
+4 MiB, so tightening probe expectations invalidates a cached PASS. Files
+ignored by git and nested git repositories are outside the gate). Functional probes then send real commands and assert on the answers,
 including register readbacks (TIM3 CCR), not firmware self-reports:
 
 ```yaml
@@ -98,10 +99,12 @@ Board profiles, probes, fixes and docs are welcome — see
 
 `hooks/flashgate_stop.py` is a Claude Code Stop hook (any harness
 implementing the same hook contract works). When the agent tries to finish after
-touching watched firmware files, the hook fingerprints the tree and allows
-instantly if that exact state already passed hardware verify (~0.7 s
-cached). Otherwise it runs the full verify on the real board and blocks
-the stop on failure, feeding the agent the board's testimony:
+touching watched firmware files, the hook fingerprints the tree (plus the
+board profile — editing verification semantics must not reuse a cached
+green) and allows instantly if that exact state already passed hardware
+verify (~0.7 s cached). Otherwise it runs the full verify on the real
+board and blocks the stop on failure, feeding the agent the board's
+testimony:
 
 ```
 [flashgate] BLOCKED (attempt 1/2): firmware changes are not verified on hardware (verify rc=7).

{flashgate-0.5.3 → flashgate-0.5.4}/README.md

@@ -31,8 +31,9 @@ Both carry the git sha plus `-dirty` when the tree differs from HEAD, so a
 passing verify proves the board is running a build of your current HEAD
 (`-dirty` marks uncommitted changes; it does not fingerprint their
 content — the Stop hook's tree fingerprint covers that side: tracked diffs
-in full, untracked files by path + size + first 4 MiB. Files ignored by
-git and nested git repositories are outside the gate). Functional probes then send real commands and assert on the answers,
+in full, untracked files and the board profile by path + size + first
+4 MiB, so tightening probe expectations invalidates a cached PASS. Files
+ignored by git and nested git repositories are outside the gate). Functional probes then send real commands and assert on the answers,
 including register readbacks (TIM3 CCR), not firmware self-reports:
 
 ```yaml
@@ -79,10 +80,12 @@ Board profiles, probes, fixes and docs are welcome — see
 
 `hooks/flashgate_stop.py` is a Claude Code Stop hook (any harness
 implementing the same hook contract works). When the agent tries to finish after
-touching watched firmware files, the hook fingerprints the tree and allows
-instantly if that exact state already passed hardware verify (~0.7 s
-cached). Otherwise it runs the full verify on the real board and blocks
-the stop on failure, feeding the agent the board's testimony:
+touching watched firmware files, the hook fingerprints the tree (plus the
+board profile — editing verification semantics must not reuse a cached
+green) and allows instantly if that exact state already passed hardware
+verify (~0.7 s cached). Otherwise it runs the full verify on the real
+board and blocks the stop on failure, feeding the agent the board's
+testimony:
 
 ```
 [flashgate] BLOCKED (attempt 1/2): firmware changes are not verified on hardware (verify rc=7).

{flashgate-0.5.3 → flashgate-0.5.4}/flashgate/board.py

@@ -70,6 +70,13 @@ def load_board(yaml_path: Path) -> Board:
         raw = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
     except (OSError, yaml.YAMLError) as exc:
         raise BoardError(f"cannot load board profile {yaml_path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        # Empty file parses to None; a list/scalar document is equally
+        # malformed — both must surface as BoardError so the Stop hook's
+        # "gate misconfigured" branch (not a traceback) handles them.
+        raise BoardError(
+            f"board profile {yaml_path} is not a mapping "
+            f"(got {type(raw).__name__})")
 
     fw = raw.get("firmware") or {}
     flash = raw.get("flash") or {}

{flashgate-0.5.3 → flashgate-0.5.4}/flashgate/flasher.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import subprocess
+import sys
 import time
 from dataclasses import dataclass
 from pathlib import Path
@@ -22,11 +23,22 @@ class FlashResult:
 
 def _kill_stlinkserver() -> None:
     """A stale stlink-server session can wedge the probe; it restarts on
-    demand, so killing it between attempts is safe."""
-    subprocess.run(
-        ["taskkill", "/F", "/IM", "stlinkserver.exe"],
-        capture_output=True, timeout=15,
-    )
+    demand, so killing it between attempts is safe. Windows-only: the
+    helper process only exists there and so does taskkill — invoking it
+    on Linux/macOS used to raise FileNotFoundError straight out of the
+    flash-retry path. Best-effort by design: a failed kill must never
+    abort the retry it precedes."""
+    if sys.platform != "win32":
+        return
+    try:
+        subprocess.run(
+            ["taskkill", "/F", "/IM", "stlinkserver.exe"],
+            capture_output=True, timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError):
+        # OSError: taskkill missing/blocked; SubprocessError covers
+        # TimeoutExpired — a kill that hangs 15 s must die quietly too.
+        pass
 
 
 def _attempt_flash(cli: Path, bin_path: Path, connect: str, address: str, start: bool) -> tuple[bool, int, str]:

{flashgate-0.5.3 → flashgate-0.5.4}/flashgate/gatestate.py

@@ -93,15 +93,42 @@ def _untracked_content_digest(fw_dir: Path) -> str:
     return h.hexdigest()
 
 
-def tree_fingerprint(fw_dir: Path) -> str:
-    """Content-identity of the working tree (not just HEAD: dirty trees with
-    different edits must NOT share a fingerprint — including edits to
-    untracked files, whose contents are hashed in explicitly)."""
+def _profile_digest(profile: Path) -> str:
+    """sha256 over the board profile's bytes (same 4 MiB cap as untracked
+    files). Identity is content-only: two profiles with identical bytes
+    define identical verification semantics; any location-dependent field
+    resolves through firmware_dir, which is fingerprinted separately."""
+    try:
+        h = hashlib.sha256()
+        with profile.open("rb") as fh:
+            remaining = _HASH_CAP_BYTES
+            while remaining > 0:
+                chunk = fh.read(min(1 << 20, remaining))
+                if not chunk:
+                    break
+                h.update(chunk)
+                remaining -= len(chunk)
+        return h.hexdigest()
+    except OSError:
+        return "<unreadable>"
+
+
+def tree_fingerprint(fw_dir: Path, profile: Path | None = None) -> str:
+    """Content-identity of the working tree AND the verification semantics.
+
+    Not just HEAD: dirty trees with different edits must NOT share a
+    fingerprint — including edits to untracked files (hashed explicitly)
+    and edits to the board profile. The profile defines what "PASS"
+    means (probe expectations, build command), so tightening or loosening
+    it after a cached PASS must invalidate that green, not reuse it —
+    same stale-PASS class as the untracked-content hole (2026-09-13
+    external review)."""
     head = _git(["rev-parse", "HEAD"], fw_dir)
     diff = _git(["diff", "HEAD"], fw_dir)
     status = _git(["status", "--porcelain"], fw_dir)
     untracked = _untracked_content_digest(fw_dir)
-    blob = "\x00".join((head, diff, status, untracked))
+    profile_part = _profile_digest(profile) if profile is not None else "<no-profile>"
+    blob = "\x00".join((head, diff, status, untracked, profile_part))
     return hashlib.sha256(blob.encode("utf-8", errors="replace")).hexdigest()
 
 

{flashgate-0.5.3 → flashgate-0.5.4}/flashgate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.5.3
+Version: 0.5.4
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Project-URL: Homepage, https://github.com/Lion-1209/flashgate
@@ -50,8 +50,9 @@ Both carry the git sha plus `-dirty` when the tree differs from HEAD, so a
 passing verify proves the board is running a build of your current HEAD
 (`-dirty` marks uncommitted changes; it does not fingerprint their
 content — the Stop hook's tree fingerprint covers that side: tracked diffs
-in full, untracked files by path + size + first 4 MiB. Files ignored by
-git and nested git repositories are outside the gate). Functional probes then send real commands and assert on the answers,
+in full, untracked files and the board profile by path + size + first
+4 MiB, so tightening probe expectations invalidates a cached PASS. Files
+ignored by git and nested git repositories are outside the gate). Functional probes then send real commands and assert on the answers,
 including register readbacks (TIM3 CCR), not firmware self-reports:
 
 ```yaml
@@ -98,10 +99,12 @@ Board profiles, probes, fixes and docs are welcome — see
 
 `hooks/flashgate_stop.py` is a Claude Code Stop hook (any harness
 implementing the same hook contract works). When the agent tries to finish after
-touching watched firmware files, the hook fingerprints the tree and allows
-instantly if that exact state already passed hardware verify (~0.7 s
-cached). Otherwise it runs the full verify on the real board and blocks
-the stop on failure, feeding the agent the board's testimony:
+touching watched firmware files, the hook fingerprints the tree (plus the
+board profile — editing verification semantics must not reuse a cached
+green) and allows instantly if that exact state already passed hardware
+verify (~0.7 s cached). Otherwise it runs the full verify on the real
+board and blocks the stop on failure, feeding the agent the board's
+testimony:
 
 ```
 [flashgate] BLOCKED (attempt 1/2): firmware changes are not verified on hardware (verify rc=7).

{flashgate-0.5.3 → flashgate-0.5.4}/flashgate.egg-info/SOURCES.txt

@@ -21,7 +21,9 @@ flashgate.egg-info/requires.txt
 flashgate.egg-info/top_level.txt
 tests/test_board.py
 tests/test_cli.py
+tests/test_flasher.py
 tests/test_gatestate.py
+tests/test_hook_stop.py
 tests/test_mcp.py
 tests/test_probes.py
 tests/test_swdsig.py

{flashgate-0.5.3 → flashgate-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashgate"
-version = "0.5.3"
+version = "0.5.4"
 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.5.3 → flashgate-0.5.4}/tests/test_board.py

@@ -63,6 +63,18 @@ class TestLoadBoard:
         b = load_board(make_profile(tmp_path, body))
         assert b.banner_regex == "BOOT git={git}"
 
+    def test_malformed_document_rejected_not_crash(self, tmp_path):
+        # Adversarial review F4: an empty file parses to None and a
+        # list/scalar document is equally malformed — both must raise
+        # BoardError (the Stop hook's "gate misconfigured" branch), never
+        # a bare AttributeError out of raw.get().
+        import pytest
+        for bad in ("", "- a\n- b\n", "just a scalar\n"):
+            p = tmp_path / "bad.yaml"
+            p.write_text(bad, encoding="utf-8")
+            with pytest.raises(BoardError):
+                load_board(p)
+
 
 class TestHeadSha:
     def test_clean_then_dirty(self, tmp_path, git_repo):

flashgate-0.5.4/tests/test_flasher.py

@@ -0,0 +1,48 @@
+"""_kill_stlinkserver guards the flash-retry path across platforms.
+
+External review (2026-09-13): the bare `taskkill` invocation raised
+FileNotFoundError on Linux/macOS, crashing the retry that follows a failed
+flash attempt — the retry loop must survive cleanup failures on any OS.
+"""
+
+from flashgate import flasher
+
+
+class TestKillStlinkserver:
+    def test_noop_off_windows(self, monkeypatch):
+        monkeypatch.setattr(flasher.sys, "platform", "linux")
+
+        def boom(*args, **kwargs):
+            raise AssertionError("no process may be spawned off Windows")
+
+        monkeypatch.setattr(flasher.subprocess, "run", boom)
+        flasher._kill_stlinkserver()          # must neither raise nor spawn
+
+    def test_windows_invokes_taskkill(self, monkeypatch):
+        monkeypatch.setattr(flasher.sys, "platform", "win32")
+        calls = []
+        monkeypatch.setattr(flasher.subprocess, "run",
+                            lambda *a, **kw: calls.append(a) or None)
+        flasher._kill_stlinkserver()
+        assert calls, "on Windows the stale stlink-server must be killed"
+        assert calls[0][0][:2] == ["taskkill", "/F"]
+
+    def test_taskkill_failure_never_aborts_retry(self, monkeypatch):
+        monkeypatch.setattr(flasher.sys, "platform", "win32")
+
+        def boom(*args, **kwargs):
+            raise OSError("blocked by policy")
+
+        monkeypatch.setattr(flasher.subprocess, "run", boom)
+        flasher._kill_stlinkserver()          # best-effort cleanup: swallow
+
+    def test_taskkill_timeout_never_aborts_retry(self, monkeypatch):
+        # Adversarial review F1: TimeoutExpired is a SubprocessError, not an
+        # OSError — the retry loop must survive a kill that hangs 15 s too.
+        monkeypatch.setattr(flasher.sys, "platform", "win32")
+
+        def hang(*args, **kwargs):
+            raise flasher.subprocess.TimeoutExpired(cmd="taskkill", timeout=15)
+
+        monkeypatch.setattr(flasher.subprocess, "run", hang)
+        flasher._kill_stlinkserver()

{flashgate-0.5.3 → flashgate-0.5.4}/tests/test_gatestate.py

@@ -110,3 +110,49 @@ class TestUntrackedFingerprintCompleteness:
         (git_repo / "NewModule").mkdir()
         (git_repo / "NewModule" / "mod.c").write_text("int x;\n")
         assert watched_paths(git_repo, DEFAULT_WATCH) == ["NewModule/mod.c"]
+
+
+class TestProfileFingerprint:
+    """The board profile defines what PASS means (probe expectations, build
+    command). Its content must be part of the fingerprint, or a cached
+    green survives edits to the verification semantics themselves."""
+
+    def test_profile_edit_changes_fingerprint(self, git_repo, tmp_path):
+        from flashgate.gatestate import tree_fingerprint
+        profile = tmp_path / "board.yaml"
+        profile.write_text("probes: [strict]\n")
+        fp1 = tree_fingerprint(git_repo, profile)
+        profile.write_text("probes: [loose]\n")     # semantics changed
+        assert tree_fingerprint(git_repo, profile) != fp1
+
+    def test_tree_untouched_by_profile_only_change(self, git_repo, tmp_path):
+        # A profile edit alone must flip the combined fingerprint while the
+        # tree-only view stays identical — the delta comes from the profile.
+        from flashgate.gatestate import tree_fingerprint
+        profile = tmp_path / "board.yaml"
+        profile.write_text("probes: [a]\n")
+        before_tree = tree_fingerprint(git_repo)
+        combined1 = tree_fingerprint(git_repo, profile)
+        profile.write_text("probes: [b]\n")
+        assert tree_fingerprint(git_repo) == before_tree
+        assert tree_fingerprint(git_repo, profile) != combined1
+
+    def test_same_content_same_fingerprint(self, git_repo, tmp_path):
+        # Content-only identity: identical bytes, different name → same digest.
+        from flashgate.gatestate import tree_fingerprint
+        a = tmp_path / "a.yaml"
+        b = tmp_path / "b.yaml"
+        a.write_text("same: true\n")
+        b.write_text("same: true\n")
+        assert tree_fingerprint(git_repo, a) == tree_fingerprint(git_repo, b)
+
+    def test_missing_profile_is_stable_not_crashing(self, git_repo, tmp_path):
+        from flashgate.gatestate import tree_fingerprint
+        ghost = tmp_path / "ghost.yaml"
+        assert tree_fingerprint(git_repo, ghost) == tree_fingerprint(git_repo, ghost)
+
+    def test_profile_none_differs_from_empty_profile(self, git_repo, tmp_path):
+        from flashgate.gatestate import tree_fingerprint
+        empty = tmp_path / "empty.yaml"
+        empty.write_text("")
+        assert tree_fingerprint(git_repo) != tree_fingerprint(git_repo, empty)

flashgate-0.5.4/tests/test_hook_stop.py

@@ -0,0 +1,85 @@
+"""Stop hook wiring: the board profile must reach the fingerprint.
+
+Gatestate-level tests prove profile edits change the fingerprint; this
+file guards the CALLER. If hooks/flashgate_stop.py ever stops passing
+board.yaml_path into tree_fingerprint, a cached PASS would survive edits
+to the verification semantics (probe expectations, build command) and no
+gatestate test would notice — this is the test that goes red.
+"""
+
+import importlib.util
+import io
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+HOOK_PATH = Path(__file__).resolve().parent.parent / "hooks" / "flashgate_stop.py"
+
+
+def load_hook():
+    spec = importlib.util.spec_from_file_location("flashgate_stop_under_test", HOOK_PATH)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+@pytest.fixture()
+def hook(git_repo, tmp_path, monkeypatch):
+    mod = load_hook()
+    # A watched change must exist, or the hook allows the stop before it
+    # ever reaches the fingerprint comparison.
+    (git_repo / "App" / "extra.c").write_text("int x;\n")
+    profile = tmp_path / "board.yaml"
+    profile.write_text("board: t\nprobes: [strict]\n")
+    board = SimpleNamespace(
+        firmware_dir=git_repo, watch_globs=("*",), yaml_path=profile,
+    )
+    monkeypatch.setattr(mod, "load_board", lambda p: board)
+    monkeypatch.delenv("FLASHGATE_BOARD", raising=False)
+    monkeypatch.setattr(sys, "argv", ["flashgate_stop.py"])
+    return mod, board, profile
+
+
+def run_stop(mod, monkeypatch, state):
+    monkeypatch.setattr(sys, "stdin", io.StringIO("{}"))
+    monkeypatch.setattr(mod.gatestate, "load_state", lambda d: dict(state))
+    return mod.main()
+
+
+class TestProfileInvalidatesCache:
+    def test_profile_edit_after_cached_pass_reruns_verify(
+            self, hook, git_repo, monkeypatch):
+        mod, board, profile = hook
+        calls = []
+
+        def fake_verify(board_arg):
+            calls.append(board_arg)
+            return 0, "PASS"
+
+        monkeypatch.setattr(mod, "run_verify", fake_verify)
+        saved = {}
+
+        def fake_save(d, **fields):
+            saved.update(fields)
+
+        monkeypatch.setattr(mod.gatestate, "save_state", fake_save)
+
+        # 1st stop: no cache → real verify → PASS cached (tree + profile).
+        assert run_stop(mod, monkeypatch, {}) == 0
+        assert len(calls) == 1
+        cached = saved["verified_fingerprint"]
+
+        # 2nd stop: identical tree AND profile → cache hit, no verify.
+        assert run_stop(mod, monkeypatch,
+                        {"verified_fingerprint": cached}) == 0
+        assert len(calls) == 1
+
+        # 3rd stop: firmware tree untouched, but the verification SEMANTICS
+        # changed (profile edit) → the cached green must NOT be reused.
+        profile.write_text("board: t\nprobes: [loose]\n")
+        assert run_stop(mod, monkeypatch,
+                        {"verified_fingerprint": cached}) == 0
+        assert len(calls) == 2, "a profile edit must force a re-verify"
+        assert saved["verified_fingerprint"] != cached