flashgate 0.4.0__py3-none-any.whl

flashgate/flasher.py

@@ -0,0 +1,132 @@
+"""Flashing via STM32CubeProgrammer CLI (ST-Link)."""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .sttools import augmented_env, find_cubeprogrammer
+
+FLASH_TIMEOUT_S = 90
+FLASH_ATTEMPTS = 3          # clone ST-Links throw transient DEV_USB_COMM_ERR
+RETRY_DELAY_S = 3.0
+
+
+@dataclass
+class FlashResult:
+    ok: bool
+    detail: str
+
+
+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,
+    )
+
+
+def _attempt_flash(cli: Path, bin_path: Path, connect: str, address: str, start: bool) -> tuple[bool, int, str]:
+    cmd = [
+        str(cli),
+        "--connect", connect,
+        "--write", str(bin_path), address,
+        "--verify",
+    ]
+    if start:
+        cmd.append("--start")
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=FLASH_TIMEOUT_S,
+            env=augmented_env(), encoding="utf-8", errors="replace",
+        )
+    except subprocess.TimeoutExpired:
+        return False, -1, "CubeProgrammer timed out (ST-Link connected? board powered?)"
+    except OSError as exc:
+        return False, -1, f"failed to run CubeProgrammer: {exc}"
+
+    output = (proc.stdout or "") + (proc.stderr or "")
+    # CubeProgrammer mixes return codes; trust the explicit download line.
+    if proc.returncode == 0 and "File download complete" in output:
+        return True, 0, output.strip()
+    return False, proc.returncode, output.strip() or f"exit code {proc.returncode}"
+
+
+def flash(bin_path: Path, connect: str, address: str, start: bool = True) -> FlashResult:
+    cli = find_cubeprogrammer()
+    if cli is None:
+        return FlashResult(False, "STM32CubeProgrammer CLI not found (bundles or PATH)")
+
+    if not bin_path.is_file():
+        return FlashResult(False, f"artifact not found: {bin_path}")
+
+    last_detail = ""
+    for attempt in range(1, FLASH_ATTEMPTS + 1):
+        ok, rc, output = _attempt_flash(cli, bin_path, connect, address, start)
+        if ok:
+            return FlashResult(True, output)
+        last_detail = f"attempt {attempt}/{FLASH_ATTEMPTS} rc={rc}: {output[-1200:]}"
+        if attempt < FLASH_ATTEMPTS:
+            _kill_stlinkserver()
+            time.sleep(RETRY_DELAY_S)
+    return FlashResult(False, last_detail)
+
+
+def write32(connect: str, value: int, address: int) -> bool:
+    """Single 32-bit memory write via a tiny temp file (CubeProgrammer's
+    --write only accepts files). Used to wipe a stale boot signature."""
+    cli = find_cubeprogrammer()
+    if cli is None:
+        return False
+    import subprocess
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        blob = Path(tmp) / "word.bin"
+        blob.write_bytes(value.to_bytes(4, "little"))
+        cmd = [str(cli), "--connect", connect,
+               "--write", str(blob), f"{address:#010x}"]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=30,
+                env=augmented_env(), encoding="utf-8", errors="replace",
+            )
+        except (subprocess.TimeoutExpired, OSError):
+            return False
+        output = (proc.stdout or "") + (proc.stderr or "")
+        return proc.returncode == 0 and "File download complete" in output
+
+
+def start_app(connect: str) -> bool:
+    """Reset and run the application (the `--start` step on its own)."""
+    cli = find_cubeprogrammer()
+    if cli is None:
+        return False
+    import subprocess
+    try:
+        proc = subprocess.run(
+            [str(cli), "--connect", connect, "--start"],
+            capture_output=True, text=True, timeout=30,
+            env=augmented_env(), encoding="utf-8", errors="replace",
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+    return proc.returncode == 0 and "achieved successfully" in (proc.stdout or "")
+
+
+def list_stlink() -> str:
+    """Doctor helper: list connected ST-Link probes."""
+    cli = find_cubeprogrammer()
+    if cli is None:
+        return "(CubeProgrammer CLI not found)"
+    try:
+        proc = subprocess.run(
+            [str(cli), "-l"], capture_output=True, text=True, timeout=30,
+            env=augmented_env(), encoding="utf-8", errors="replace",
+        )
+        return (proc.stdout or "") + (proc.stderr or "")
+    except (subprocess.SubprocessError, OSError) as exc:
+        return f"(probe listing failed: {exc})"

flashgate/gatestate.py

@@ -0,0 +1,81 @@
+"""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/mcp_server.py

@@ -0,0 +1,221 @@
+"""flashgate MCP server: expose the hardware gate to any MCP-capable agent.
+
+Run via `flashgate-mcp` (stdio transport). Requires the optional extra:
+
+    pip install "flashgate[mcp]"
+
+Wiring (.mcp.json, Claude Code compatible):
+
+    {"mcpServers": {"flashgate": {
+        "command": "flashgate-mcp",
+        "args": ["--board", "/path/to/boards/apollo-h743.yaml"]}}}
+
+Tools: board_info, doctor, build, flash, verify, probe, console_send,
+console_read. Every tool returns plain text (ANSI stripped) — the same
+output the CLI prints, plus the flashgate exit-code contract.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import sys
+import time
+from contextlib import redirect_stdout
+from pathlib import Path
+
+try:
+    from mcp.server.mcpserver import MCPServer as _Server   # mcp 2.x
+except ImportError:
+    try:
+        from mcp.server.fastmcp import FastMCP as _Server   # mcp 1.x
+    except ImportError as exc:  # pragma: no cover - friendly extra hint
+        raise SystemExit(
+            "flashgate MCP server needs the optional dependency: "
+            'pip install "flashgate[mcp]"'
+        ) from exc
+
+from . import __version__, flasher, probes as probe_mod, serialmon
+from .board import Board, BoardError, default_board_path, load_board
+from . import cli as cli_mod
+
+mcp = _Server(f"flashgate {__version__}")
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+_BOARD_ARG: list[str] = []          # set from argv by main()
+
+
+def _board(board: str | None = None) -> Board:
+    """Resolve the board profile: tool arg > server --board arg > default."""
+    source = board or (_BOARD_ARG[0] if _BOARD_ARG else None)
+    path = Path(source) if source else default_board_path()
+    if path is None or not Path(path).is_file():
+        raise BoardError(f"board profile not found: {source or 'boards/*.yaml'}")
+    return load_board(Path(path))
+
+
+def _capture(fn, *args) -> str:
+    """Run a CLI command function, return its printed output, ANSI-stripped."""
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = fn(*args)
+    text = _ANSI.sub("", buf.getvalue()).strip()
+    return f"exit code: {rc}\n{text}"
+
+
+def _err(exc: Exception) -> str:
+    return f"error: {exc}"
+
+
+@mcp.tool()
+def board_info(board: str | None = None) -> str:
+    """Show the active board profile: firmware dir, artifact, watch globs,
+    banner contract, and the functional probes it defines."""
+    try:
+        b = _board(board)
+    except BoardError as exc:
+        return _err(exc)
+    lines = [
+        f"board       : {b.name} ({b.mcu})",
+        f"description : {b.description}",
+        f"firmware    : {b.firmware_dir}",
+        f"artifact    : {b.artifact}",
+        f"flash       : {b.flash_connect} @ {b.flash_address}",
+        f"banner      : {b.banner_regex}",
+        f"gate.watch  : {', '.join(b.watch_globs)}",
+    ]
+    try:
+        names = list(probe_mod.load_probes(b.yaml_path))
+        lines.append(f"probes      : {', '.join(names) if names else '(none)'}")
+    except (OSError, ValueError) as exc:
+        lines.append(f"probes      : (unloadable: {exc})")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def doctor(board: str | None = None) -> str:
+    """Check hardware prerequisites: ST-Link probe, console serial port,
+    toolchain. Run this first when anything else fails (exit code 6)."""
+    try:
+        return _capture(cli_mod.cmd_doctor, _board(board))
+    except BoardError as exc:
+        return _err(exc)
+
+
+@mcp.tool()
+def build(board: str | None = None) -> str:
+    """Build the firmware (incremental). Exit codes: 0 ok, 1 build failed."""
+    try:
+        return _capture(cli_mod.cmd_build, _board(board))
+    except BoardError as exc:
+        return _err(exc)
+
+
+@mcp.tool()
+def flash(board: str | None = None) -> str:
+    """Flash + verify + start via ST-Link (with auto-retry). Exit codes:
+    0 ok, 2 flash failed, 6 environment error."""
+    try:
+        return _capture(cli_mod.cmd_flash, _board(board))
+    except BoardError as exc:
+        return _err(exc)
+
+
+@mcp.tool()
+def verify(board: str | None = None) -> str:
+    """The full gate: build -> flash -> boot banner -> sha check -> all
+    functional probes. Exit 0 means the BOARD ITSELF confirms the firmware
+    works. 1 build, 2 flash, 3 no banner, 4 boot error, 5 sha mismatch,
+    6 env, 7 probe failure."""
+    try:
+        return _capture(cli_mod.cmd_verify, _board(board), ["all"])
+    except BoardError as exc:
+        return _err(exc)
+
+
+@mcp.tool()
+def probe(names: list[str] | None = None, board: str | None = None) -> str:
+    """Run functional probes against the ALREADY RUNNING firmware (no
+    rebuild/reflash). names=None runs every probe. Exit 7 = probe failed."""
+    try:
+        b = _board(board)
+    except BoardError as exc:
+        return _err(exc)
+    port, why = serialmon.resolve_console_port(b.serial_port, b.usb_vid, b.usb_pids)
+    if port is None:
+        return f"error: console serial unresolved — {why}"
+    try:
+        conn = serialmon.open_flush(port, b.baudrate)
+    except Exception as exc:  # pyserial SerialException
+        return f"error: cannot open {port}: {exc}"
+    try:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = cli_mod._run_probes(b, names, conn)
+        return f"exit code: {rc}\n{_ANSI.sub('', buf.getvalue()).strip()}"
+    finally:
+        conn.close()
+
+
+@mcp.tool()
+def console_send(line: str, wait_s: float = 1.0, board: str | None = None) -> str:
+    """Send ONE line to the firmware console (e.g. 'led0?' or 'selftest')
+    and return the response lines received within wait_s seconds."""
+    try:
+        b = _board(board)
+    except BoardError as exc:
+        return _err(exc)
+    port, why = serialmon.resolve_console_port(b.serial_port, b.usb_vid, b.usb_pids)
+    if port is None:
+        return f"error: console serial unresolved — {why}"
+    try:
+        conn = serialmon.open_flush(port, b.baudrate)
+    except Exception as exc:
+        return f"error: cannot open {port}: {exc}"
+    try:
+        conn.write((line + "\r\n").encode())
+        deadline = time.monotonic() + max(0.1, wait_s)
+        out = ""
+        while time.monotonic() < deadline:
+            out += conn.read(256).decode("utf-8", errors="replace")
+        return out.strip() or "(no response)"
+    finally:
+        conn.close()
+
+
+@mcp.tool()
+def console_read(seconds: float = 2.0, board: str | None = None) -> str:
+    """Read whatever the firmware prints on the console for N seconds
+    (banner, self-test output, fault dumps)."""
+    try:
+        b = _board(board)
+    except BoardError as exc:
+        return _err(exc)
+    port, why = serialmon.resolve_console_port(b.serial_port, b.usb_vid, b.usb_pids)
+    if port is None:
+        return f"error: console serial unresolved — {why}"
+    try:
+        conn = serialmon.open_flush(port, b.baudrate)
+    except Exception as exc:
+        return f"error: cannot open {port}: {exc}"
+    try:
+        deadline = time.monotonic() + max(0.1, seconds)
+        out = ""
+        while time.monotonic() < deadline:
+            out += conn.read(256).decode("utf-8", errors="replace")
+        return out.strip() or "(silence)"
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if "--board" in args:
+        i = args.index("--board")
+        if i + 1 < len(args):
+            _BOARD_ARG.append(args[i + 1])
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

flashgate/probes.py

@@ -0,0 +1,171 @@
+"""Probe runner: send/expect/assert steps against the console protocol.
+
+A probe is claim-proportional functional verification: the host drives the
+board over the console and asserts on what the board reports — including
+hardware register readbacks like the PWM CCR value. Any `ERR` line from the
+firmware, an expect mismatch, a timeout, or a failed assert fails the probe.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from functools import lru_cache
+
+import serial
+import yaml
+
+# Response template: "OK bat mv={mv}" mirrors the firmware's printf format,
+# with {name} where a value appears and {name:d} when it must be digits.
+_PLACEHOLDER = re.compile(r"\{(\w+)(?::(d))?\}")
+
+
+@lru_cache(maxsize=None)
+def compile_pattern(expect: str, anchor: bool = True) -> re.Pattern[str]:
+    """Compile an expect string into a line-matching pattern.
+
+    Three accepted forms, commonest first:
+      "OK bat mv={mv}"   printf mirror: {mv} captures \\S+, {mv:d} captures digits
+      "OK demo on"       the line must equal this, verbatim
+      "/^OK .* on$/"     slash-delimited raw regex (escape hatch)
+
+    Strings that already look like regex (legacy profiles: named groups,
+    ^/$ anchors) pass through unchanged, so old yaml keeps working.
+
+    anchor=True pins the template to the full line (probe steps match one
+    line at a time); anchor=False leaves it free-floating (the banner is
+    searched in a streaming transcript where \\r\\n precedes it).
+    """
+    if len(expect) > 1 and expect.startswith("/") and expect.endswith("/"):
+        return re.compile(expect[1:-1])
+    if "(?P<" in expect or expect.startswith("^") or expect.endswith("$"):
+        return re.compile(expect)
+    parts = []
+    pos = 0
+    for m in _PLACEHOLDER.finditer(expect):
+        parts.append(re.escape(expect[pos:m.start()]))
+        sub = "\\d+" if m.group(2) == "d" else "\\S+"
+        parts.append(f"(?P<{m.group(1)}>{sub})")
+        pos = m.end()
+    parts.append(re.escape(expect[pos:]))
+    body = "".join(parts)
+    return re.compile(f"^{body}$" if anchor else body)
+
+
+@dataclass
+class ProbeStep:
+    send: str
+    expect: str                      # regex matched against one response line
+    assert_expr: str | None = None   # over expect's named groups, e.g. "ccr > 0"
+
+
+@dataclass
+class Probe:
+    name: str
+    description: str = ""
+    step_timeout_s: float = 3.0
+    steps: list[ProbeStep] = field(default_factory=list)
+
+
+@dataclass
+class ProbeResult:
+    ok: bool
+    step_index: int | None = None    # failing step (0-based)
+    detail: str = ""
+
+
+class ProbeError(Exception):
+    pass
+
+
+def load_probes(yaml_path) -> dict[str, Probe]:
+    raw = yaml.safe_load(yaml_path.read_text(encoding="utf-8")) or {}
+    probes: dict[str, Probe] = {}
+    for name, spec in (raw.get("probes") or {}).items():
+        probe = Probe(
+            name=name,
+            description=spec.get("description", ""),
+            step_timeout_s=float(spec.get("step_timeout_s", 3.0)),
+            steps=[
+                ProbeStep(
+                    send=str(s["send"]),
+                    expect=str(s["expect"]),
+                    assert_expr=s.get("assert"),
+                )
+                for s in spec.get("steps", [])
+            ],
+        )
+        if not probe.steps:
+            raise ProbeError(f"probe {name!r} has no steps")
+        probes[name] = probe
+    return probes
+
+
+def _clause(groups: dict[str, str], clause: str) -> bool:
+    for op in ("==", "!=", ">=", "<=", ">", "<"):
+        if op in clause:
+            name, _, value = clause.partition(op)
+            name, value = name.strip(), value.strip()
+            if name not in groups:
+                return False
+            left, right = groups[name], value
+            if left.lstrip("-").isdigit() and right.lstrip("-").isdigit():
+                left, right = int(left), int(right)
+            return {
+                "==": left == right, "!=": left != right,
+                ">": left > right,   "<": left < right,
+                ">=": left >= right, "<=": left <= right,
+            }[op]
+    return False
+
+
+def eval_assert(expr: str, groups: dict[str, str]) -> bool:
+    """Tiny conjunction evaluator: `name OP value and name OP value`.
+    No eval() — probes are data, not code."""
+    return all(_clause(groups, c) for c in expr.split(" and "))
+
+
+def run_probe(conn: serial.Serial, probe: Probe, echo: bool = True) -> ProbeResult:
+    for idx, step in enumerate(probe.steps):
+        if echo:
+            print(f"    step {idx + 1}: {probe.name}> {step.send}")
+        conn.write((step.send + "\r\n").encode())
+
+        deadline = time.monotonic() + probe.step_timeout_s
+        buffer = ""
+        matched = False
+        last_line = ""
+        while time.monotonic() < deadline:
+            chunk = conn.read(256)
+            if chunk:
+                buffer += chunk.decode("utf-8", errors="replace")
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    line = line.strip("\r")
+                    if not line:
+                        continue
+                    if echo:
+                        print(f"    board: {line}")
+                    last_line = line
+                    if line.startswith("ERR"):
+                        return ProbeResult(False, idx,
+                                           f"firmware error: {line!r} at step {idx + 1}")
+                    m = compile_pattern(step.expect).search(line)
+                    if m:
+                        groups = m.groupdict()
+                        if step.assert_expr and not eval_assert(step.assert_expr, groups):
+                            return ProbeResult(
+                                False, idx,
+                                f"assert failed: {step.assert_expr!r} "
+                                f"against {groups} (step {idx + 1})")
+                        matched = True
+                        break
+                if matched:
+                    break
+        if not matched:
+            seen = f", last response: {last_line!r}" if last_line else ""
+            return ProbeResult(False, idx,
+                               f"timeout waiting for /{step.expect}/ after "
+                               f"{step.send!r} (step {idx + 1}){seen}")
+    return ProbeResult(True)