flashgate 0.4.0__tar.gz

flashgate-0.4.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,187 @@
+# 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/flashgate/__init__.py

@@ -0,0 +1,8 @@
+"""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"

flashgate-0.4.0/flashgate/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

flashgate-0.4.0/flashgate/board.py

@@ -0,0 +1,120 @@
+"""Board profile loading: one yaml per board, everything declarative."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from .gatestate import DEFAULT_WATCH
+
+
+class BoardError(Exception):
+    pass
+
+
+@dataclass
+class Board:
+    name: str
+    mcu: str
+    description: str
+    firmware_dir: Path
+    configure_command: str
+    build_command: str
+    artifact: Path
+    flash_connect: str
+    flash_address: str
+    serial_port: str
+    usb_vid: int
+    usb_pids: tuple[int, ...]
+    baudrate: int
+    banner_regex: str
+    banner_timeout_s: float
+    error_patterns: tuple[str, ...]
+    watch_globs: tuple[str, ...]
+    evidence_mode: str
+    sig_address: int
+    sig_size: int
+    yaml_path: Path
+
+    def head_sha(self) -> str | None:
+        """Firmware identity the banner should carry: short HEAD sha plus
+        '-dirty' when the working tree differs from HEAD (same algorithm as
+        cmake/firmware_identity.cmake, so the comparison is meaningful)."""
+        try:
+            sha = subprocess.run(
+                ["git", "rev-parse", "--short=7", "HEAD"],
+                cwd=self.firmware_dir, capture_output=True, text=True,
+                timeout=15, check=True,
+            ).stdout.strip()
+            status = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=self.firmware_dir, capture_output=True, text=True,
+                timeout=15, check=True,
+            ).stdout.strip()
+            if status:
+                sha += "-dirty"
+            return sha
+        except (subprocess.SubprocessError, OSError):
+            return None
+
+
+def load_board(yaml_path: Path) -> Board:
+    yaml_path = yaml_path.resolve()
+    try:
+        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
+
+    fw = raw.get("firmware") or {}
+    flash = raw.get("flash") or {}
+    ser = raw.get("serial") or {}
+
+    base = yaml_path.parent
+    ev = raw.get("evidence") or {}
+    sig = ev.get("signature") or {}
+    banner = str(ser.get("banner") or ser.get("banner_regex") or "")
+    if not banner:
+        raise BoardError(f"board profile {yaml_path.name} missing key: 'banner'")
+    try:
+        board = Board(
+            name=raw["board"],
+            mcu=raw.get("mcu", ""),
+            description=raw.get("description", ""),
+            firmware_dir=(base / fw["dir"]).resolve(),
+            configure_command=fw.get("configure", ""),
+            build_command=fw["build"],
+            artifact=(base / fw["dir"] / fw["artifact"]).resolve(),
+            flash_connect=flash.get("connect", "port=SWD"),
+            flash_address=str(flash.get("address", "0x08000000")),
+            serial_port=str(ser.get("port", "") or ""),
+            usb_vid=int(str(ser.get("vid", "0x1A86")), 0),
+            usb_pids=tuple(int(str(p), 0) for p in ser.get("pids", [])),
+            baudrate=int(ser.get("baudrate", 115200)),
+            banner_regex=banner,
+            banner_timeout_s=float(ser.get("banner_timeout_s", 15)),
+            error_patterns=tuple(ser.get("error_patterns", [])),
+            watch_globs=tuple((raw.get("gate") or {}).get("watch", DEFAULT_WATCH)),
+            evidence_mode=str(ev.get("mode", "auto")),
+            sig_address=int(str(sig.get("address", "0x2001FF00")), 0),
+            sig_size=int(sig.get("size", 64)),
+            yaml_path=yaml_path,
+        )
+    except KeyError as exc:
+        raise BoardError(f"board profile {yaml_path.name} missing key: {exc}") from exc
+
+    if not board.firmware_dir.is_dir():
+        raise BoardError(f"firmware dir does not exist: {board.firmware_dir}")
+    return board
+
+
+def default_board_path() -> Path | None:
+    """First yaml in <repo>/boards — the repo layout default."""
+    boards_dir = Path(__file__).resolve().parent.parent / "boards"
+    if boards_dir.is_dir():
+        for candidate in sorted(boards_dir.glob("*.yaml")):
+            return candidate
+    return None