flashgate 0.4.0__py3-none-any.whl

flashgate/serialmon.py

@@ -0,0 +1,106 @@
+"""Console serial: resolve the USB-TTL adapter, wait for the boot banner."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import time
+from dataclasses import dataclass
+
+import serial
+from serial.tools import list_ports
+
+ENV_PORT = "FLASHGATE_SERIAL_PORT"
+
+
+@dataclass
+class BannerResult:
+    matched: bool
+    groups: dict[str, str] | None
+    transcript: str
+    error_hit: str | None
+
+
+def resolve_console_port(
+    explicit_port: str,
+    vid: int,
+    pids: tuple[int, ...],
+) -> tuple[str | None, str]:
+    """Layered port resolution. Returns (device, why) so doctor can explain.
+
+    1. explicit port (yaml `serial.port` or env FLASHGATE_SERIAL_PORT)
+    2. VID/PID hint — matches common USB-TTL bridges (CH340/CP210x/FT232...)
+    3. sole serial port on the machine
+    The banner regex remains the final identity proof in every case: a wrong
+    port simply never matches and verify times out with a clear error.
+    """
+    explicit = (os.environ.get(ENV_PORT) or explicit_port or "").strip()
+    if explicit:
+        return explicit, "explicit (config/env override)"
+
+    ports = list_ports.comports()
+    for p in ports:
+        if p.vid == vid and (not pids or p.pid in pids):
+            return p.device, f"VID/PID hint {p.vid:04X}:{p.pid:04X} ({p.description})"
+    if len(ports) == 1:
+        return ports[0].device, f"sole serial port ({ports[0].description})"
+
+    if not ports:
+        return None, "no serial ports on this machine — plug in the USB-TTL adapter"
+    names = ", ".join(f"{p.device} ({p.description})" for p in ports)
+    return None, f"ambiguous: multiple serial ports [{names}] — set serial.port or {ENV_PORT}"
+
+
+def open_flush(device: str, baudrate: int) -> serial.Serial:
+    """Open and drain stale output (a previous firmware's banner).
+
+    verify() keeps this connection open across the flash step on purpose:
+    the banner emitted right at the `--start` reset then sits in the OS
+    buffer instead of being lost to a close/reopen race.
+    """
+    conn = serial.Serial(device, baudrate, timeout=0.2)
+    conn.reset_input_buffer()
+    conn.reset_output_buffer()
+    return conn
+
+
+def wait_on(
+    conn: serial.Serial,
+    banner_regex: str,
+    error_patterns: tuple[str, ...],
+    timeout_s: float,
+    echo: bool = True,
+) -> BannerResult:
+    """Read from an open connection until banner / error pattern / timeout."""
+    from .probes import compile_pattern
+
+    pattern = compile_pattern(banner_regex, anchor=False)
+    deadline = time.monotonic() + timeout_s
+    transcript = ""
+
+    while time.monotonic() < deadline:
+        chunk = conn.read(512)
+        if chunk:
+            text = chunk.decode("utf-8", errors="replace")
+            transcript += text
+            if echo:
+                sys.stdout.write(text)
+                sys.stdout.flush()
+            m = pattern.search(transcript)
+            if m:
+                return BannerResult(True, m.groupdict(), transcript, None)
+            for err in error_patterns:
+                if err in transcript:
+                    return BannerResult(False, None, transcript, err)
+
+    return BannerResult(False, None, transcript, None)
+
+
+def console_forever(device: str, baudrate: int) -> None:
+    with serial.Serial(device, baudrate, timeout=0.2) as conn:
+        while True:
+            chunk = conn.read(512)
+            if chunk:
+                sys.stdout.write(chunk.decode("utf-8", errors="replace"))
+                sys.stdout.flush()

flashgate/sttools.py

@@ -0,0 +1,56 @@
+"""STM32Cube bundle discovery: toolchain + CubeProgrammer live under
+%LOCALAPPDATA%/stm32cube/bundles/<tool>/<version>/bin on Windows when the
+STM32Cube CLT / VSCode extension installed them."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+
+def _bundle_root() -> Path:
+    local = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    return Path(local) / "stm32cube" / "bundles"
+
+
+def bundle_bin_dirs() -> list[Path]:
+    """All bundle bin dirs (cmake/ninja/gcc/programmer...), newest version
+    of each tool first so PATH lookups win with the newest."""
+    root = _bundle_root()
+    if not root.is_dir():
+        return []
+
+    def version_key(p: Path) -> tuple:
+        raw = p.parent.name  # the <version> directory
+        return tuple(int(x) if x.isdigit() else 0 for x in re.split(r"[+.-]", raw))
+
+    dirs = [p for p in root.glob("*/*/bin") if p.is_dir()]
+    return sorted(dirs, key=lambda p: (p.parts[-3], tuple(-x for x in version_key(p))))
+
+
+def augmented_env() -> dict[str, str]:
+    """subprocess env with all ST bundle bins prepended to PATH."""
+    env = os.environ.copy()
+    dirs = [str(p) for p in bundle_bin_dirs()]
+    if dirs:
+        env["PATH"] = os.pathsep.join(dirs + [env.get("PATH", "")])
+    return env
+
+
+def find_cubeprogrammer() -> Path | None:
+    """Newest STM32_Programmer_CLI.exe under the bundles, or PATH lookup."""
+    candidates = list((_bundle_root() / "programmer").glob("*/bin/STM32_Programmer_CLI.exe"))
+
+    def version_key(p: Path) -> tuple:
+        raw = p.parent.parent.name
+        return tuple(int(x) if x.isdigit() else 0 for x in re.split(r"[+.-]", raw))
+
+    if candidates:
+        return max(candidates, key=version_key)
+
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        guess = Path(entry) / "STM32_Programmer_CLI.exe"
+        if guess.is_file():
+            return guess
+    return None

flashgate/swdsig.py

@@ -0,0 +1,83 @@
+"""SWD signature evidence: read the firmware's fixed-address boot identity
+through the ST-Link alone — no serial cable required.
+
+The firmware publishes a 64-byte struct at SIGRAM (end of AXI SRAM):
+magic written LAST, CRC32 over the first 48 bytes. A debugger read that
+races the boot-time writes fails the CRC and is simply retried.
+"""
+
+from __future__ import annotations
+
+import struct
+import tempfile
+import time
+import zlib
+from pathlib import Path
+
+from .flasher import FLASH_ATTEMPTS  # reuse attempt count semantics
+from .sttools import augmented_env, find_cubeprogrammer
+
+SIG_MAGIC = 0xF1A5C0DE
+READ_TIMEOUT_S = 30
+
+
+class SwdError(Exception):
+    pass
+
+
+def read_ram(connect: str, address: int, size: int) -> bytes | None:
+    """One CubeProgrammer memory read (HotPlug: does not halt the core)."""
+    cli = find_cubeprogrammer()
+    if cli is None:
+        raise SwdError("STM32CubeProgrammer CLI not found")
+    import subprocess
+
+    with tempfile.TemporaryDirectory() as tmp:
+        out = Path(tmp) / "sig.bin"
+        cmd = [str(cli), "--connect", connect, "--read", hex(address), str(size), str(out)]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=READ_TIMEOUT_S,
+                env=augmented_env(), encoding="utf-8", errors="replace",
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise SwdError("CubeProgrammer read timed out") from exc
+        if proc.returncode != 0 or not out.is_file():
+            output = (proc.stdout or "") + (proc.stderr or "")
+            raise SwdError(f"RAM read failed: {output.strip()[-300:]}")
+        return out.read_bytes()[:size]
+
+
+def parse_signature(buf: bytes) -> dict | None:
+    """Validate magic + CRC and decode the identity. None = not (yet) valid."""
+    if len(buf) < 64:
+        return None
+    magic, version, flags = struct.unpack_from("<IHH", buf, 0)
+    if magic != SIG_MAGIC:
+        return 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
+    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}
+
+
+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)."""
+    deadline = time.monotonic() + timeout_s
+    last = "no valid signature yet"
+    while time.monotonic() < deadline:
+        try:
+            buf = read_ram(connect, address, size)
+        except SwdError as exc:
+            last = str(exc)
+            time.sleep(1.0)
+            continue
+        info = parse_signature(buf or b"")
+        if info is not None:
+            return info, ""
+        time.sleep(0.5)
+    return None, last

flashgate-0.4.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: flashgate
+Version: 0.4.0
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# flashgate
+
+flashgate answers one specific question: the firmware you just built — does
+it actually run on the board?
+
+It automates the whole chain: compile, flash over ST-Link, wait for the
+board to report its own identity, then drive the actual feature over the
+console and assert on hardware register readbacks. Any broken step ends
+with a non-zero exit code and a reason.
+
+```
+build → flash over ST-Link → board boots → evidence → probes → exit code
+```
+
+[中文说明](#中文说明) | [使用说明（推荐先读这份）](docs/GUIDE.md)
+
+## How the board testifies
+
+Two evidence channels, picked per bench (`evidence.mode`: uart / swd / auto):
+
+The firmware prints its identity over the console UART, and also publishes
+a 64-byte signature (magic + git sha + build time + CRC32) at a fixed RAM
+address that the host reads through the ST-Link alone — no serial cable
+needed for boot verification:
+
+```
+FLASHGATE-BOOT board=apollo-h743 git=2c58bd3 build=2026-08-28T07:26:35Z rtos=FreeRTOS
+```
+
+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,
+including register readbacks (TIM3 CCR), not firmware self-reports:
+
+```yaml
+- send: "led0?"
+  expect: "OK led0 state={state} ccr={ccr:d}"   # mirror of the firmware's printf
+  assert: "state == BREATH and ccr <= 1000"
+```
+
+## Quick start
+
+```bash
+pip install -e .                 # Python 3.11+
+pip install -e ".[mcp]"          # optional MCP server
+
+flashgate doctor                 # ST-Link / serial / toolchain sanity
+flashgate verify --all-probes    # build → flash → evidence → sha → probes
+echo $?                          # 0 = the board confirms it works
+```
+
+Requires an ST-Link; a USB-TTL adapter on the console UART adds probes.
+The repo ships a complete buildable example for the ALIENTEK Apollo
+STM32H743 (`examples/apollo-h743/`) with the Stop hook pre-wired, so a
+fresh clone verifies out of the box once wired up.
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| 0 | verified |
+| 1 | build failed |
+| 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) |
+| 7 | functional probe failed |
+
+## The Stop hook
+
+`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:
+
+```
+[flashgate] BLOCKED (attempt 1/2): firmware changes are not verified on hardware (verify rc=7).
+[flashgate] last verify output:
+    step 1: led-demo> led0 breath
+    board: OK led0 state=OFF          ← readback exposes the silent no-op
+```
+
+The same broken tree is blocked at most twice, then released with a loud
+warning — the session can never wedge, and a failure is never silently
+swallowed.
+
+## Install as a Claude Code plugin
+
+The repo doubles as a Claude Code plugin: the Stop hook, an MCP server,
+a board-integration skill and /flashgate commands, all at once:
+
+```
+pip install git+https://github.com/Lion-1209/flashgate        # CLI + hook runtime
+pip install "flashgate[mcp] @ git+https://github.com/Lion-1209/flashgate"  # + MCP
+```
+
+Then inside Claude Code:
+
+```
+/plugin marketplace add Lion-1209/flashgate
+/plugin install flashgate@flashgate
+```
+
+The hook needs to know your board profile: set `FLASHGATE_BOARD` to your
+board yaml (or a repo `boards/` default is used when present). Without a
+profile the gate stays idle and says so.
+
+## MCP server
+
+```json
+{ "mcpServers": { "flashgate": {
+    "command": "flashgate-mcp",
+    "args": ["--board", "/path/to/boards/apollo-h743.yaml"] } } }
+```
+
+board_info, doctor, build, flash, verify, probe, console_send,
+console_read. Any MCP-capable agent can drive the board directly. mcp 1.x
+and 2.x supported.
+
+## Demos
+
+Real-hardware recordings, indexed in [demo/](demo/README.md): doctor,
+green-path verify, boot-timeout catch, probe catching a silent no-op,
+Stop-hook escalation — plus the full session of a real Claude Code agent
+getting blocked, diagnosing the firmware↔profile contract, fixing both
+sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
+
+## Board profiles
+
+One yaml per board (`boards/`): build command, artifact, flash address,
+serial adapter hints, banner template, probes, watch globs. The console-side
+USB adapter is a property of your bench, not the board — port resolution
+goes explicit `serial.port` / `FLASHGATE_SERIAL_PORT`, then VID/PID hint,
+then the sole serial port, with the banner match as the final identity
+proof. See the [guide](docs/GUIDE.md#6-固件怎么对接-flashgate) for the
+firmware-side integration recipe (three levels, with code) and the
+full profile field reference.
+
+## Status
+
+Boot gate, probe gate, Stop hook, MCP server, SWD signature channel — all
+implemented and validated on real hardware. Windows-first; Linux/macOS
+untested.
+
+## License
+
+MIT
+
+---
+
+# 中文说明
+
+flashgate 回答一个很具体的问题：刚编译出来的固件，烧到板子上到底能
+不能跑。它把整条链路自动化：编译、ST-Link 烧录、等板子报告身份、经
+串口实际调用功能并断言，任何一步断了就以非零退出码结束。
+
+完整的使用说明在 [docs/GUIDE.md](docs/GUIDE.md)：接线、安装、第一次
+验证、给自己的板子写档案、探针写法、Stop hook 和 MCP 的配置、排错。
+
+要点：
+
+- 板子有两种方式自证：串口 banner，或者在固定 RAM 地址发布 64 字节
+  签名（后者只靠 ST-Link 就能验证，不用串口线）
+- 版本身份带 `-dirty` 语义，验证通过意味着板上跑的就是当前工作区
+- 探针下真命令、断言硬件寄存器读回值；响应报的是实际状态不是回声，
+  静默失效的设置第一步就会露馅
+- Stop hook 挂进 Claude Code：agent 改了固件没过真机验证就说"完成"，
+  会被拦下并收到板子的失败证词；同一棵坏树最多拦两次，之后放行但
+  打警告，会话不会被卡死
+- 仓库带完整的示例固件（examples/apollo-h743），接好线 clone 下来
+  就能跑通第一次验证
+
+```bash
+pip install -e ".[mcp]"
+flashgate doctor                  # 体检
+flashgate verify --all-probes     # 完整验证
+echo $?
+```
+
+六个真机演示 GIF 在 [demo/](demo/)，包括一段完整的 Claude Code 会话：
+agent 改固件、被拦、自己定位到固件与板卡档案的契约不一致、两侧改齐、
+真机通过后放行。
+
+MIT License

flashgate-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+flashgate/__init__.py,sha256=Uz8PQ4_6aJyawXxFLxITQea35LHE6isOBD0WE-fIkBM,284
+flashgate/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+flashgate/board.py,sha256=g16zvmJcsoaaEUs6WdBplRZODEORPMZZn5kz5QhSgl4,4109
+flashgate/cli.py,sha256=3fmUQl0xFPXRSYuSRm4IN7Gco_LsReffjbPWr3yq0Qk,18235
+flashgate/flasher.py,sha256=7rezPunWcLWDWy7V6B308PZwNOOKCT0EKg6o_77oN2U,4619
+flashgate/gatestate.py,sha256=nLVV_E20yaNd-TTjGV3At3dYKwWL73zAip6irN4dXw8,2733
+flashgate/mcp_server.py,sha256=-YlNunexA8IC3lyeCVTJT5H2iaCK-Tvs7UpBLXQeqs8,7396
+flashgate/probes.py,sha256=i0cld8iBIvgUb7uUa5nXvzDW4gQgoB_rZIN03_TKpfg,6358
+flashgate/serialmon.py,sha256=cBNSVcH1jmBw0rhibin36l7fTtQqDLNwxJYll1JjWoA,3477
+flashgate/sttools.py,sha256=dCP-25JYIZvKd1WtMdY-pO5qd-RBLLT_NqFLB_WakHo,1927
+flashgate/swdsig.py,sha256=KqTKHeIREJLFfocSJn34fDTNx45VnrMf-KNYUQw3LaE,3036
+flashgate-0.4.0.dist-info/licenses/LICENSE,sha256=M4DdcSR3Z1VwwpIziutxKWK7AIYkUuj9R_raDA-Uy5s,1073
+flashgate-0.4.0.dist-info/METADATA,sha256=99gm-vtw1L64_bG_bmGa0iUiEUdkYIRESwxsMZiSLjQ,7498
+flashgate-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flashgate-0.4.0.dist-info/entry_points.txt,sha256=j7rNuE8toLqBj7qXuwfXhAI_xDy6Ta5_8FX2UKxS8CE,91
+flashgate-0.4.0.dist-info/top_level.txt,sha256=yO2i60mrqfucJB7D8yIlLA27b4tNUaU0jGBGGBgFEU4,10
+flashgate-0.4.0.dist-info/RECORD,,

flashgate-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flashgate-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+flashgate = flashgate.cli:main
+flashgate-mcp = flashgate.mcp_server:main

flashgate-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lion (Lion-1209)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flashgate-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flashgate