flashgate 0.5.2__tar.gz → 0.5.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.5.2
+Version: 0.5.3
 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
@@ -47,8 +47,11 @@ FLASHGATE-BOOT board=apollo-h743 git=2c58bd3 build=2026-08-28T07:26:35Z rtos=Fre
 ```
 
 Both carry the git sha plus `-dirty` when the tree differs from HEAD, so a
-passing verify proves the board is running exactly the code you're looking
-at. Functional probes then send real commands and assert on the answers,
+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,
 including register readbacks (TIM3 CCR), not firmware self-reports:
 
 ```yaml

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

@@ -28,8 +28,11 @@ FLASHGATE-BOOT board=apollo-h743 git=2c58bd3 build=2026-08-28T07:26:35Z rtos=Fre
 ```
 
 Both carry the git sha plus `-dirty` when the tree differs from HEAD, so a
-passing verify proves the board is running exactly the code you're looking
-at. Functional probes then send real commands and assert on the answers,
+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,
 including register readbacks (TIM3 CCR), not firmware self-reports:
 
 ```yaml

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

@@ -48,11 +48,13 @@ class Board:
             sha = subprocess.run(
                 ["git", "rev-parse", "--short=7", "HEAD"],
                 cwd=self.firmware_dir, capture_output=True, text=True,
+                encoding="utf-8", errors="replace",
                 timeout=15, check=True,
             ).stdout.strip()
             status = subprocess.run(
                 ["git", "status", "--porcelain"],
                 cwd=self.firmware_dir, capture_output=True, text=True,
+                encoding="utf-8", errors="replace",
                 timeout=15, check=True,
             ).stdout.strip()
             if status:

flashgate-0.5.3/flashgate/gatestate.py

@@ -0,0 +1,144 @@
+"""Gate state: fingerprint the firmware tree, remember the last PASS.
+
+The Stop hook only re-runs the (slow) hardware verify when the firmware tree
+actually changed since the last passing run. The fingerprint covers HEAD,
+the full diff against HEAD, and the untracked-file list — so any content
+change to a watched file produces a new fingerprint.
+
+Escalation: after MAX_CONSECUTIVE_BLOCKS failed blocks for the SAME
+fingerprint, the gate releases with a warning instead of blocking forever
+(coderio VerifyGate semantics: never wedge the session, never silently
+give up).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from datetime import datetime, timezone
+from fnmatch import fnmatch
+from pathlib import Path
+
+STATE_DIR = ".flashgate"
+STATE_FILE = "state.json"
+MAX_CONSECUTIVE_BLOCKS = 2
+
+DEFAULT_WATCH = [
+    "*.c", "*.h", "*.s", "*.ld", "*.ioc",
+    "CMakeLists.txt", "*.cmake", "cmake/*",
+]
+
+
+def _git(args: list[str], cwd: Path) -> str:
+    # errors="surrogateescape": `ls-files -z` emits raw UTF-8 path bytes and
+    # text=True alone would decode with the ANSI code page (cp936 on a
+    # Chinese Windows) — a non-ASCII path then kills the reader thread,
+    # stdout becomes None, and the Stop hook crashes to exit 1, which the
+    # hook contract treats as non-blocking: the gate would fail OPEN.
+    try:
+        proc = subprocess.run(
+            ["git", *args], cwd=cwd, capture_output=True, text=True,
+            encoding="utf-8", errors="surrogateescape",
+            timeout=20, check=True,
+        )
+        return proc.stdout or ""
+    except (subprocess.SubprocessError, OSError):
+        return ""
+
+
+_HASH_CAP_BYTES = 4 * 1024 * 1024   # per file: length + first 4 MiB
+
+
+def _untracked_files(fw_dir: Path) -> list[str]:
+    """Untracked files, recursively, gitignore-respecting, no quoting.
+
+    `git status --porcelain` collapses a new directory to '?? dir/' (hiding
+    every file inside) and C-escapes non-ASCII paths under core.quotepath —
+    both let content edits slip past a content digest. `ls-files
+    --others --exclude-standard -z` lists real paths, NUL-separated."""
+    out = _git(["ls-files", "--others", "--exclude-standard", "-z"], fw_dir)
+    return sorted(p for p in out.split("\x00") if p)
+
+
+def _untracked_content_digest(fw_dir: Path) -> str:
+    """Digest over the CONTENT of untracked files.
+
+    Found by the 2026-09-13 external review: git diff ignores untracked
+    files and git status lists only their paths, so editing an untracked
+    source file after a cached PASS kept the fingerprint unchanged — the
+    Stop hook reused the stale green. Hashing path + size + content closes
+    it. The gate's own state dir is excluded: save_state() rewrites a
+    timestamp there, and letting it feed the fingerprint would invalidate
+    every cached PASS."""
+    h = hashlib.sha256()
+    for path in _untracked_files(fw_dir):
+        if path == ".flashgate" or path.startswith(".flashgate/"):
+            continue
+        f = fw_dir / path
+        try:
+            size = f.stat().st_size
+            h.update(f"{path}\x00{size}\x00".encode("utf-8", errors="replace"))
+            with f.open("rb") as fh:               # chunked: never OOM on a
+                remaining = min(size, _HASH_CAP_BYTES)  # stray huge file
+                while remaining > 0:
+                    chunk = fh.read(min(1 << 20, remaining))
+                    if not chunk:
+                        break
+                    h.update(chunk)
+                    remaining -= len(chunk)
+        except OSError:
+            h.update(f"{path}\x00<unreadable>\x00".encode("utf-8", errors="replace"))
+        h.update(b"\x00")
+    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)."""
+    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))
+    return hashlib.sha256(blob.encode("utf-8", errors="replace")).hexdigest()
+
+
+def watched_paths(fw_dir: Path, patterns: list[str]) -> list[str]:
+    """Working-tree changes that match the watch globs (gate triggers)."""
+    status = _git(["status", "--porcelain"], fw_dir)
+    watched: list[str] = []
+    for line in status.splitlines():
+        if line.startswith("?? "):
+            continue     # untracked: handled below, dir-collapsed in status
+        path = line[3:].strip().strip('"')
+        if " -> " in path:                     # rename: judge by the new name
+            path = path.split(" -> ")[1]
+        if path and any(fnmatch(path, pat) for pat in patterns):
+            watched.append(path)
+    # Untracked files come from ls-files: a new directory collapses to a
+    # single '?? dir/' status line that no *.c glob can match, which used
+    # to mean new files in new dirs never even triggered the gate.
+    for path in _untracked_files(fw_dir):
+        if any(fnmatch(path, pat) for pat in patterns):
+            watched.append(path)
+    return watched
+
+
+def state_path(fw_dir: Path) -> Path:
+    return fw_dir / STATE_DIR / STATE_FILE
+
+
+def load_state(fw_dir: Path) -> dict:
+    try:
+        return json.loads(state_path(fw_dir).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def save_state(fw_dir: Path, **fields) -> None:
+    path = state_path(fw_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"updated": datetime.now(timezone.utc).isoformat(), **fields}
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.5.2
+Version: 0.5.3
 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
@@ -47,8 +47,11 @@ FLASHGATE-BOOT board=apollo-h743 git=2c58bd3 build=2026-08-28T07:26:35Z rtos=Fre
 ```
 
 Both carry the git sha plus `-dirty` when the tree differs from HEAD, so a
-passing verify proves the board is running exactly the code you're looking
-at. Functional probes then send real commands and assert on the answers,
+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,
 including register readbacks (TIM3 CCR), not firmware self-reports:
 
 ```yaml

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

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

@@ -0,0 +1,112 @@
+"""Tree fingerprint and watched-path filtering over a real git repo."""
+
+from flashgate import gatestate
+
+
+class TestWatchedPaths:
+    def test_watch_filter(self, git_repo):
+        (git_repo / "App" / "extra.c").write_text("int x;\n")
+        (git_repo / "readme2.md").write_text("docs\n")
+        watched = gatestate.watched_paths(git_repo, ["*.c", "*.h"])
+        assert "App/extra.c" in watched
+        assert all(w.endswith((".c", ".h")) for w in watched)
+
+    def test_no_changes(self, git_repo):
+        assert gatestate.watched_paths(git_repo, ["*.c"]) == []
+
+
+class TestTreeFingerprint:
+    def test_stable_when_unchanged(self, git_repo):
+        a = gatestate.tree_fingerprint(git_repo)
+        b = gatestate.tree_fingerprint(git_repo)
+        assert a == b
+
+    def test_changes_with_content(self, git_repo):
+        before = gatestate.tree_fingerprint(git_repo)
+        (git_repo / "App" / "main.c").write_text("int main(void) { return 2; }\n")
+        assert gatestate.tree_fingerprint(git_repo) != before
+
+    def test_two_dirty_states_differ(self, git_repo):
+        (git_repo / "App" / "main.c").write_text("/* a */\n")
+        a = gatestate.tree_fingerprint(git_repo)
+        (git_repo / "App" / "main.c").write_text("/* b */\n")
+        assert gatestate.tree_fingerprint(git_repo) != a
+
+
+class TestState:
+    def test_roundtrip_and_missing(self, tmp_path, git_repo):
+        assert gatestate.load_state(git_repo) == {}
+        gatestate.save_state(git_repo, verified_fingerprint="abc", consecutive_blocks=0)
+        s = gatestate.load_state(git_repo)
+        assert s["verified_fingerprint"] == "abc"
+        assert "updated" in s
+
+
+class TestUntrackedContentFingerprint:
+    def test_untracked_content_edit_changes_fingerprint(self, git_repo):
+        # 2026-09-13 external-review finding: git status lists untracked
+        # paths only, so editing an untracked file's CONTENT kept the tree
+        # fingerprint unchanged — the Stop hook would reuse a cached PASS
+        # over silently-modified code. Contents must be hashed in.
+        from flashgate.gatestate import tree_fingerprint
+        untracked = git_repo / "App" / "new.c"
+        untracked.write_text("int x = 1;\n")
+        fp1 = tree_fingerprint(git_repo)
+        untracked.write_text("int x = 999; /* silently changed */\n")
+        fp2 = tree_fingerprint(git_repo)
+        assert fp1 != fp2, "untracked content edit MUST change the fingerprint"
+
+    def test_untracked_appearance_changes_fingerprint(self, git_repo):
+        from flashgate.gatestate import tree_fingerprint
+        fp1 = tree_fingerprint(git_repo)
+        (git_repo / "App" / "added.c").write_text("int y;\n")
+        assert tree_fingerprint(git_repo) != fp1
+
+    def test_tracked_edit_still_changes_fingerprint(self, git_repo):
+        from flashgate.gatestate import tree_fingerprint
+        fp1 = tree_fingerprint(git_repo)
+        (git_repo / "App" / "main.c").write_text("int main(void){return 1;}\n")
+        assert tree_fingerprint(git_repo) != fp1
+
+    def test_clean_tree_fingerprint_stable(self, git_repo):
+        from flashgate.gatestate import tree_fingerprint
+        assert tree_fingerprint(git_repo) == tree_fingerprint(git_repo)
+
+
+class TestUntrackedFingerprintCompleteness:
+    """Residual holes found by the adversarial re-review of the first fix:
+    untracked NEW directories (git status collapses to '?? dir/') and
+    non-ASCII paths (core.quotepath escaping) must not hide content edits,
+    and the gate's own state writes must not invalidate the PASS cache."""
+
+    def test_new_directory_content_edit_changes_fingerprint(self, git_repo):
+        from flashgate.gatestate import tree_fingerprint
+        mod = git_repo / "NewModule"
+        mod.mkdir()
+        (mod / "mod.c").write_text("int f(void){return 1;}\n")
+        fp1 = tree_fingerprint(git_repo)
+        (mod / "mod.c").write_text("int f(void){return 999;}\n")
+        fp2 = tree_fingerprint(git_repo)
+        assert fp1 != fp2, "content edit inside an untracked NEW dir must be visible"
+
+    def test_non_ascii_path_content_edit_changes_fingerprint(self, git_repo):
+        from flashgate.gatestate import tree_fingerprint
+        src = git_repo / "App" / "新模块.c"
+        src.write_text("int a = 1;\n")
+        fp1 = tree_fingerprint(git_repo)
+        src.write_text("int a = 999; /* silently changed */\n")
+        fp2 = tree_fingerprint(git_repo)
+        assert fp1 != fp2, "non-ASCII path (quotepath escaping) must not hide edits"
+
+    def test_state_dir_writes_do_not_change_fingerprint(self, git_repo):
+        from flashgate.gatestate import save_state, tree_fingerprint
+        save_state(git_repo, status="pass", fingerprint="x")   # state dir exists
+        fp1 = tree_fingerprint(git_repo)
+        save_state(git_repo, status="pass", fingerprint="y")   # timestamp moves
+        assert tree_fingerprint(git_repo) == fp1, ".flashgate/ must stay out of the digest"
+
+    def test_new_dir_source_triggers_watch(self, git_repo):
+        from flashgate.gatestate import DEFAULT_WATCH, watched_paths
+        (git_repo / "NewModule").mkdir()
+        (git_repo / "NewModule" / "mod.c").write_text("int x;\n")
+        assert watched_paths(git_repo, DEFAULT_WATCH) == ["NewModule/mod.c"]

flashgate-0.5.2/flashgate/gatestate.py

@@ -1,81 +0,0 @@
-"""Gate state: fingerprint the firmware tree, remember the last PASS.
-
-The Stop hook only re-runs the (slow) hardware verify when the firmware tree
-actually changed since the last passing run. The fingerprint covers HEAD,
-the full diff against HEAD, and the untracked-file list — so any content
-change to a watched file produces a new fingerprint.
-
-Escalation: after MAX_CONSECUTIVE_BLOCKS failed blocks for the SAME
-fingerprint, the gate releases with a warning instead of blocking forever
-(coderio VerifyGate semantics: never wedge the session, never silently
-give up).
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import subprocess
-from datetime import datetime, timezone
-from fnmatch import fnmatch
-from pathlib import Path
-
-STATE_DIR = ".flashgate"
-STATE_FILE = "state.json"
-MAX_CONSECUTIVE_BLOCKS = 2
-
-DEFAULT_WATCH = [
-    "*.c", "*.h", "*.s", "*.ld", "*.ioc",
-    "CMakeLists.txt", "*.cmake", "cmake/*",
-]
-
-
-def _git(args: list[str], cwd: Path) -> str:
-    try:
-        return subprocess.run(
-            ["git", *args], cwd=cwd, capture_output=True, text=True,
-            timeout=20, check=True,
-        ).stdout
-    except (subprocess.SubprocessError, OSError):
-        return ""
-
-
-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)."""
-    head = _git(["rev-parse", "HEAD"], fw_dir)
-    diff = _git(["diff", "HEAD"], fw_dir)
-    status = _git(["status", "--porcelain"], fw_dir)
-    blob = "\x00".join((head, diff, status))
-    return hashlib.sha256(blob.encode("utf-8", errors="replace")).hexdigest()
-
-
-def watched_paths(fw_dir: Path, patterns: list[str]) -> list[str]:
-    """Working-tree changes that match the watch globs (gate triggers)."""
-    status = _git(["status", "--porcelain"], fw_dir)
-    watched: list[str] = []
-    for line in status.splitlines():
-        path = line[3:].strip().strip('"')
-        if " -> " in path:                     # rename: judge by the new name
-            path = path.split(" -> ")[1]
-        if path and any(fnmatch(path, pat) for pat in patterns):
-            watched.append(path)
-    return watched
-
-
-def state_path(fw_dir: Path) -> Path:
-    return fw_dir / STATE_DIR / STATE_FILE
-
-
-def load_state(fw_dir: Path) -> dict:
-    try:
-        return json.loads(state_path(fw_dir).read_text(encoding="utf-8"))
-    except (OSError, ValueError):
-        return {}
-
-
-def save_state(fw_dir: Path, **fields) -> None:
-    path = state_path(fw_dir)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    payload = {"updated": datetime.now(timezone.utc).isoformat(), **fields}
-    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")

flashgate-0.5.2/tests/test_gatestate.py

@@ -1,42 +0,0 @@
-"""Tree fingerprint and watched-path filtering over a real git repo."""
-
-from flashgate import gatestate
-
-
-class TestWatchedPaths:
-    def test_watch_filter(self, git_repo):
-        (git_repo / "App" / "extra.c").write_text("int x;\n")
-        (git_repo / "readme2.md").write_text("docs\n")
-        watched = gatestate.watched_paths(git_repo, ["*.c", "*.h"])
-        assert "App/extra.c" in watched
-        assert all(w.endswith((".c", ".h")) for w in watched)
-
-    def test_no_changes(self, git_repo):
-        assert gatestate.watched_paths(git_repo, ["*.c"]) == []
-
-
-class TestTreeFingerprint:
-    def test_stable_when_unchanged(self, git_repo):
-        a = gatestate.tree_fingerprint(git_repo)
-        b = gatestate.tree_fingerprint(git_repo)
-        assert a == b
-
-    def test_changes_with_content(self, git_repo):
-        before = gatestate.tree_fingerprint(git_repo)
-        (git_repo / "App" / "main.c").write_text("int main(void) { return 2; }\n")
-        assert gatestate.tree_fingerprint(git_repo) != before
-
-    def test_two_dirty_states_differ(self, git_repo):
-        (git_repo / "App" / "main.c").write_text("/* a */\n")
-        a = gatestate.tree_fingerprint(git_repo)
-        (git_repo / "App" / "main.c").write_text("/* b */\n")
-        assert gatestate.tree_fingerprint(git_repo) != a
-
-
-class TestState:
-    def test_roundtrip_and_missing(self, tmp_path, git_repo):
-        assert gatestate.load_state(git_repo) == {}
-        gatestate.save_state(git_repo, verified_fingerprint="abc", consecutive_blocks=0)
-        s = gatestate.load_state(git_repo)
-        assert s["verified_fingerprint"] == "abc"
-        assert "updated" in s