flashgate 0.4.2__tar.gz → 0.5.0__tar.gz

{flashgate-0.4.2 → flashgate-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.4.2
+Version: 0.5.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
@@ -133,7 +133,7 @@ profile the gate stays idle and says so.
 ```
 
 board_info, doctor, build, flash, verify, probe, console_send,
-console_read. Any MCP-capable agent can drive the board directly. mcp 1.x
+console_read. Any MCP-capable agent can drive the board directly. Every tool returns a structured result envelope (status, stable code, summary, CLI exit_code, log) — never a bare log to parse. mcp 1.x
 and 2.x supported.
 
 ## Demos

{flashgate-0.4.2 → flashgate-0.5.0}/README.md

@@ -117,7 +117,7 @@ profile the gate stays idle and says so.
 ```
 
 board_info, doctor, build, flash, verify, probe, console_send,
-console_read. Any MCP-capable agent can drive the board directly. mcp 1.x
+console_read. Any MCP-capable agent can drive the board directly. Every tool returns a structured result envelope (status, stable code, summary, CLI exit_code, log) — never a bare log to parse. mcp 1.x
 and 2.x supported.
 
 ## Demos

{flashgate-0.4.2 → flashgate-0.5.0}/flashgate/cli.py

@@ -2,7 +2,9 @@
 
 Exit-code contract (the M3 Stop hook enforces these):
   0 verified | 1 build failed | 2 flash failed | 3 no banner (timeout)
-  4 boot error string | 5 git sha mismatch | 6 environment error
+  4 boot error string | 5 identity mismatch (git sha or board name)
+  6 environment error (incl. probes required but console unavailable)
+  7 functional probe failed
 """
 
 from __future__ import annotations

flashgate-0.5.0/flashgate/mcp_server.py

@@ -0,0 +1,351 @@
+"""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 a `flashgate.results.Result` envelope (schema_version,
+status, stable code, summary, CLI exit_code, data, warnings, policy) —
+never a bare log the model has to parse. With mcp 2.x the envelope is
+emitted as MCP structuredContent (registered via structured_output=True)
+plus a JSON text block; on the mcp 1.x fallback the JSON text is still
+produced. The text log of the underlying CLI run travels in data["log"].
+Native ToolAnnotations (readOnly/destructive hints) are attached when the
+installed SDK supports them.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+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
+
+try:
+    from mcp.types import ToolAnnotations
+except ImportError:                                         # pre-1.9 SDK
+    ToolAnnotations = None                                  # type: ignore[assignment]
+
+from . import __version__, flasher, probes as probe_mod, serialmon
+from . import results
+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()
+
+# Policy metadata (design doc §5.5 risk ladder), carried in every envelope.
+P_READ = {"risk": "R0"}                 # read-only, no device state change
+P_PROBE = {"risk": "R1"}                # drives device state, recoverable
+P_BUILD = {"risk": "R0"}                # host-side only
+P_FLASH = {"risk": "R2"}                # modifies the device
+P_VERIFY = {"risk": "R2"}               # includes a flash
+P_CONSOLE_SEND = {"risk": "R1"}         # open-world line into the firmware
+
+
+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) -> tuple[int, str]:
+    """Run a CLI command function, return (exit code, printed output ANSI-stripped)."""
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = fn(*args)
+    return rc, _ANSI.sub("", buf.getvalue()).strip()
+
+
+def _cli_result(label: str, rc: int, log: str, policy: dict) -> results.Result:
+    """Envelope from a CLI run: the log rides in data['log'], the summary is
+    the log's first meaningful line so a model can triage without reading it."""
+    first = next((ln for ln in log.splitlines() if ln.strip()), "")
+    summary = f"{label}: {first[:140]}" if first else f"{label}: exit {rc}"
+    return results.from_exit(rc, summary, log=log, policy=policy)
+
+
+def _serial_error(exc: Exception, port: str | None, policy: dict) -> results.Result:
+    return results.failure(
+        f"cannot open {port}: {exc}" if port else str(exc),
+        code=results.TRANSPORT_ERROR, status="incomplete", policy=policy)
+
+
+def _register(annotations=None, structured: bool = False):
+    """@tool decorator tolerant of mcp 2.x and 1.x: forwards annotations /
+    structured_output only when the installed SDK's decorator accepts them."""
+    def deco(fn):
+        params = inspect.signature(mcp.tool).parameters
+        kwargs = {}
+        if annotations is not None and "annotations" in params:
+            kwargs["annotations"] = annotations
+        if structured and "structured_output" in params:
+            kwargs["structured_output"] = True
+        return mcp.tool(**kwargs)(fn)
+    return deco
+
+
+def _ann(**kwargs):
+    return ToolAnnotations(**kwargs) if ToolAnnotations is not None else None
+
+
+def _safe(policy: dict):
+    """Last-resort guard: an exception escaping a tool must surface as an
+    INTERNAL_ERROR envelope, never as an MCP protocol error — the
+    envelope contract (design doc §5.1) has no room for bare crashes."""
+    def deco(fn):
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            try:
+                return fn(*args, **kwargs)
+            except Exception as exc:            # noqa: BLE001 - by design
+                return results.failure(
+                    f"{type(exc).__name__}: {exc}",
+                    code=results.INTERNAL_ERROR, policy=policy)
+        return wrapper
+    return deco
+
+
+@_register(annotations=_ann(readOnlyHint=True), structured=True)
+@_safe(P_READ)
+def board_info(board: str | None = None) -> results.Result:
+    """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 results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_READ)
+    probes: list[str] = []
+    warnings: list[str] = []
+    try:
+        probes = list(probe_mod.load_probes(b.yaml_path))
+    except (OSError, ValueError) as exc:
+        warnings.append(f"probes unloadable: {exc}")
+    r = results.ok(
+        f"{b.name} ({b.mcu}) — {len(probes)} probe(s) defined",
+        data={
+            "board": b.name,
+            "mcu": b.mcu,
+            "description": b.description,
+            "firmware_dir": str(b.firmware_dir),
+            "artifact": str(b.artifact),
+            "flash": f"{b.flash_connect} @ {b.flash_address}",
+            "banner": b.banner_regex,
+            "gate_watch": list(b.watch_globs),
+            "probes": probes,
+        },
+        policy=P_READ)
+    r.warnings.extend(warnings)
+    return r
+
+
+@_register(annotations=_ann(readOnlyHint=True), structured=True)
+@_safe(P_READ)
+def doctor(board: str | None = None) -> results.Result:
+    """Check hardware prerequisites: ST-Link probe, console serial port,
+    toolchain. Run this first when anything else fails (exit code 6)."""
+    try:
+        rc, log = _capture(cli_mod.cmd_doctor, _board(board))
+    except BoardError as exc:
+        return results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_READ)
+    return _cli_result("doctor", rc, log, P_READ)
+
+
+@_register(annotations=_ann(idempotentHint=True), structured=True)
+@_safe(P_BUILD)
+def build(board: str | None = None) -> results.Result:
+    """Build the firmware (incremental). Fails with code BUILD_FAILED."""
+    try:
+        rc, log = _capture(cli_mod.cmd_build, _board(board))
+    except BoardError as exc:
+        return results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_BUILD)
+    return _cli_result("build", rc, log, P_BUILD)
+
+
+@_register(annotations=_ann(destructiveHint=True), structured=True)
+@_safe(P_FLASH)
+def flash(board: str | None = None) -> results.Result:
+    """Flash + verify + start via ST-Link (with auto-retry). Destructive:
+    replaces the firmware running on the board."""
+    try:
+        rc, log = _capture(cli_mod.cmd_flash, _board(board))
+    except BoardError as exc:
+        return results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_FLASH)
+    return _cli_result("flash", rc, log, P_FLASH)
+
+
+@_register(annotations=_ann(destructiveHint=True), structured=True)
+@_safe(P_VERIFY)
+def verify(board: str | None = None) -> results.Result:
+    """The full gate: build -> flash -> boot evidence -> identity check ->
+    all functional probes. status=succeeded means the BOARD ITSELF confirms
+    the firmware works. Failure codes: BUILD_FAILED, FLASH_FAILED,
+    BOOT_EVIDENCE_TIMEOUT, BOOT_ERROR, IDENTITY_MISMATCH,
+    CAPABILITY_UNAVAILABLE (console needed by probes but unavailable),
+    PROBE_FAILED."""
+    try:
+        rc, log = _capture(cli_mod.cmd_verify, _board(board), ["all"])
+    except BoardError as exc:
+        return results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_VERIFY)
+    return _cli_result("verify", rc, log, P_VERIFY)
+
+
+@_register(annotations=_ann(readOnlyHint=False), structured=True)
+@_safe(P_PROBE)
+def probe(names: list[str] | None = None, board: str | None = None) -> results.Result:
+    """Run functional probes against the ALREADY RUNNING firmware (no
+    rebuild/reflash). names=None or [] runs every probe (same semantics as
+    the CLI). The probe stage needs the console UART; without it the result
+    is incomplete / CAPABILITY_UNAVAILABLE — never a pass."""
+    try:
+        b = _board(board)
+    except BoardError as exc:
+        return results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_PROBE)
+    try:
+        available = list(probe_mod.load_probes(b.yaml_path))
+    except (OSError, ValueError, probe_mod.ProbeError) as exc:
+        return results.failure(f"cannot load probes: {exc}",
+                               code=results.CAPABILITY_UNAVAILABLE,
+                               status="incomplete", policy=P_PROBE)
+    requested = names or None                     # [] means "all", like the CLI
+    if requested is not None:
+        unknown = [n for n in requested if n not in available]
+        if unknown:
+            return results.failure(
+                f"unknown probe {unknown[0]!r}; available: {available}",
+                code=results.INVALID_ARGUMENT, policy=P_PROBE)
+    port, why = serialmon.resolve_console_port(b.serial_port, b.usb_vid, b.usb_pids)
+    if port is None:
+        return results.failure(
+            f"console serial unresolved — {why}",
+            code=results.CAPABILITY_UNAVAILABLE, status="incomplete",
+            policy=P_PROBE)
+    try:
+        conn = serialmon.open_flush(port, b.baudrate)
+    except Exception as exc:  # pyserial SerialException
+        return _serial_error(exc, port, P_PROBE)
+    try:
+        rc, log = _capture(cli_mod._run_probes, b, requested, conn)
+    finally:
+        conn.close()
+    return _cli_result("probe", rc, log, P_PROBE)
+
+
+@_register(annotations=_ann(readOnlyHint=False, openWorldHint=True), structured=True)
+@_safe(P_CONSOLE_SEND)
+def console_send(line: str, wait_s: float = 1.0, board: str | None = None) -> results.Result:
+    """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 results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_CONSOLE_SEND)
+    port, why = serialmon.resolve_console_port(b.serial_port, b.usb_vid, b.usb_pids)
+    if port is None:
+        return results.failure(
+            f"console serial unresolved — {why}",
+            code=results.CAPABILITY_UNAVAILABLE, status="incomplete",
+            policy=P_CONSOLE_SEND)
+    try:
+        conn = serialmon.open_flush(port, b.baudrate)
+    except Exception as exc:  # pyserial SerialException
+        return _serial_error(exc, port, P_CONSOLE_SEND)
+    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")
+    finally:
+        conn.close()
+    r = results.ok(f"sent {line!r}" + (" (no response)" if not out.strip() else ""),
+                   data={"sent": line, "wait_s": wait_s,
+                         "response": out.strip()},
+                   policy=P_CONSOLE_SEND)
+    if not out.strip():
+        r.warnings.append("no response within wait_s")
+    return r
+
+
+@_register(annotations=_ann(readOnlyHint=True), structured=True)
+@_safe(P_READ)
+def console_read(seconds: float = 2.0, board: str | None = None) -> results.Result:
+    """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 results.failure(str(exc), code=results.PROFILE_NOT_FOUND,
+                               policy=P_READ)
+    port, why = serialmon.resolve_console_port(b.serial_port, b.usb_vid, b.usb_pids)
+    if port is None:
+        return results.failure(
+            f"console serial unresolved — {why}",
+            code=results.CAPABILITY_UNAVAILABLE, status="incomplete",
+            policy=P_READ)
+    try:
+        conn = serialmon.open_flush(port, b.baudrate)
+    except Exception as exc:  # pyserial SerialException
+        return _serial_error(exc, port, P_READ)
+    try:
+        deadline = time.monotonic() + max(0.1, seconds)
+        out = ""
+        while time.monotonic() < deadline:
+            out += conn.read(256).decode("utf-8", errors="replace")
+    finally:
+        conn.close()
+    r = results.ok(f"read {seconds:.1f}s of console output"
+                   + (" (console silent)" if not out.strip() else ""),
+                   data={"text": out.strip()}, policy=P_READ)
+    if not out.strip():
+        r.warnings.append("console silent for the whole window")
+    return r
+
+
+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-0.5.0/flashgate/results.py

@@ -0,0 +1,89 @@
+"""Unified result envelope for flashgate MCP tools (design doc §7).
+
+Every MCP tool returns a Result: machine-decidable status, a stable code,
+a human summary, the CLI exit code as a compatibility layer, and the
+payload. "Command succeeded" and "hardware verified" are different things;
+`status` speaks only in evidence terms.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+SCHEMA_VERSION = "1.0"
+
+Status = Literal["succeeded", "failed", "incomplete", "cancelled", "timed_out"]
+
+# Stable machine codes (design doc §7.2). Extensible; never repurpose one.
+OK = "OK"
+BUILD_FAILED = "BUILD_FAILED"
+FLASH_FAILED = "FLASH_FAILED"
+RESET_FAILED = "RESET_FAILED"
+BOOT_EVIDENCE_TIMEOUT = "BOOT_EVIDENCE_TIMEOUT"
+BOOT_ERROR = "BOOT_ERROR"
+IDENTITY_MISMATCH = "IDENTITY_MISMATCH"
+PROBE_FAILED = "PROBE_FAILED"
+CAPABILITY_UNAVAILABLE = "CAPABILITY_UNAVAILABLE"
+TRANSPORT_ERROR = "TRANSPORT_ERROR"
+ADAPTER_ERROR = "ADAPTER_ERROR"
+INTERNAL_ERROR = "INTERNAL_ERROR"
+PROFILE_NOT_FOUND = "PROFILE_NOT_FOUND"      # board yaml missing/unloadable
+INVALID_ARGUMENT = "INVALID_ARGUMENT"
+
+# CLI exit-code contract (board yaml comment) -> envelope semantics.
+# 6 = env/prereq: a required step COULD NOT RUN -> "incomplete", never "passed".
+_EXIT_STATUS: dict[int, Status] = {
+    0: "succeeded", 1: "failed", 2: "failed", 3: "timed_out",
+    4: "failed", 5: "failed", 6: "incomplete", 7: "failed",
+}
+_EXIT_CODE: dict[int, str] = {
+    0: OK, 1: BUILD_FAILED, 2: FLASH_FAILED, 3: BOOT_EVIDENCE_TIMEOUT,
+    4: BOOT_ERROR, 5: IDENTITY_MISMATCH, 6: CAPABILITY_UNAVAILABLE,
+    7: PROBE_FAILED,
+}
+
+
+class Result(BaseModel):
+    """The envelope every flashgate MCP tool returns."""
+
+    schema_version: str = SCHEMA_VERSION
+    status: Status
+    code: str
+    summary: str
+    exit_code: int | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    evidence: list[dict[str, Any]] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    policy: dict[str, Any] = Field(default_factory=dict)
+
+
+def ok(summary: str, *, data: dict | None = None,
+       policy: dict | None = None) -> Result:
+    return Result(status="succeeded", code=OK, summary=summary,
+                  data=data or {}, policy=policy or {})
+
+
+def failure(summary: str, *, code: str = INTERNAL_ERROR,
+            status: Status = "failed", data: dict | None = None,
+            policy: dict | None = None) -> Result:
+    return Result(status=status, code=code, summary=summary,
+                  data=data or {}, policy=policy or {})
+
+
+def from_exit(rc: int, summary: str, *, log: str | None = None,
+              data: dict | None = None,
+              policy: dict | None = None) -> Result:
+    """Envelope from the CLI exit-code contract (the compat layer)."""
+    payload = dict(data or {})
+    if log:
+        payload["log"] = log
+    return Result(
+        status=_EXIT_STATUS.get(rc, "failed"),
+        code=_EXIT_CODE.get(rc, INTERNAL_ERROR),
+        summary=summary,
+        exit_code=rc,
+        data=payload,
+        policy=policy or {},
+    )

{flashgate-0.4.2 → flashgate-0.5.0}/flashgate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.4.2
+Version: 0.5.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
@@ -133,7 +133,7 @@ profile the gate stays idle and says so.
 ```
 
 board_info, doctor, build, flash, verify, probe, console_send,
-console_read. Any MCP-capable agent can drive the board directly. mcp 1.x
+console_read. Any MCP-capable agent can drive the board directly. Every tool returns a structured result envelope (status, stable code, summary, CLI exit_code, log) — never a bare log to parse. mcp 1.x
 and 2.x supported.
 
 ## Demos

{flashgate-0.4.2 → flashgate-0.5.0}/flashgate.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ flashgate/flasher.py
 flashgate/gatestate.py
 flashgate/mcp_server.py
 flashgate/probes.py
+flashgate/results.py
 flashgate/serialmon.py
 flashgate/sttools.py
 flashgate/swdsig.py
@@ -21,5 +22,6 @@ flashgate.egg-info/top_level.txt
 tests/test_board.py
 tests/test_cli.py
 tests/test_gatestate.py
+tests/test_mcp.py
 tests/test_probes.py
 tests/test_swdsig.py

{flashgate-0.4.2 → flashgate-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashgate"
-version = "0.4.2"
+version = "0.5.0"
 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.4.2 → flashgate-0.5.0}/tests/test_cli.py

@@ -146,3 +146,14 @@ class TestAutoRouting:
         monkeypatch.setattr(cli, "_verify_uart", fake_uart)
         assert cli.cmd_verify(board, None, None) == cli.EXIT_OK
         assert seen["mode"] == "uart"
+
+
+class TestEnvelopeCoupling:
+    def test_exit_env_maps_to_incomplete_never_succeeded(self):
+        # Belt-and-suspenders (mutation finding M5): the constant every
+        # fail-closed guard asserts must map to "incomplete" in the MCP
+        # envelope. If the mapping ever flips to "succeeded", a check that
+        # could not run would count as a pass.
+        from flashgate import results
+        assert results.from_exit(cli.EXIT_ENV, "x").status == "incomplete"
+        assert results.from_exit(cli.EXIT_PROBE_FAIL, "x").status == "failed"

flashgate-0.5.0/tests/test_mcp.py

@@ -0,0 +1,197 @@
+"""MCP contract tests: every tool returns the unified Result envelope,
+stable codes map from the CLI exit contract, and structuredContent carries
+the envelope on mcp 2.x. Programmatic call_tool — no transport needed."""
+
+import asyncio
+import json
+from types import SimpleNamespace
+
+import pytest
+
+pytest.importorskip("mcp")
+
+from flashgate import mcp_server as srv
+from flashgate import results
+
+
+class TestExitMapping:
+    def test_all_eight_exit_codes_map(self):
+        expect = {
+            0: ("succeeded", results.OK),
+            1: ("failed", results.BUILD_FAILED),
+            2: ("failed", results.FLASH_FAILED),
+            3: ("timed_out", results.BOOT_EVIDENCE_TIMEOUT),
+            4: ("failed", results.BOOT_ERROR),
+            5: ("failed", results.IDENTITY_MISMATCH),
+            6: ("incomplete", results.CAPABILITY_UNAVAILABLE),
+            7: ("failed", results.PROBE_FAILED),
+        }
+        for rc, (status, code) in expect.items():
+            r = results.from_exit(rc, "s")
+            assert r.status == status and r.code == code and r.exit_code == rc
+
+    def test_unknown_exit_code_is_internal_error(self):
+        r = results.from_exit(99, "s")
+        assert r.status == "failed" and r.code == results.INTERNAL_ERROR
+
+    def test_log_rides_in_data(self):
+        r = results.from_exit(0, "s", log="line1\nline2")
+        assert r.data["log"] == "line1\nline2"
+
+    def test_json_round_trip(self):
+        r = results.from_exit(7, "probe broke", log="x")
+        parsed = json.loads(r.model_dump_json())
+        assert parsed["code"] == results.PROBE_FAILED
+
+
+class TestRegisteredTools:
+    TOOLS = {"board_info", "doctor", "build", "flash", "verify",
+             "probe", "console_send", "console_read"}
+
+    def test_all_tools_registered(self):
+        async def go():
+            return {t.name for t in await srv.mcp.list_tools()}
+        assert asyncio.run(go()) == self.TOOLS
+
+    def test_annotations_attached_when_supported(self):
+        async def go():
+            return {t.name: t.annotations for t in await srv.mcp.list_tools()}
+        anns = asyncio.run(go())
+        if srv.ToolAnnotations is None:                 # pre-1.9 SDK
+            pytest.skip("SDK lacks ToolAnnotations")
+        assert anns["board_info"].read_only_hint is True
+        assert anns["flash"].destructive_hint is True
+        assert anns["verify"].destructive_hint is True
+        assert anns["console_read"].read_only_hint is True
+
+    def test_every_tool_is_envelope_typed(self):
+        async def go():
+            out = {}
+            for t in await srv.mcp.list_tools():
+                out[t.name] = (t.output_schema or {}).get("properties", {})
+            return out
+        props = asyncio.run(go())
+        for name in self.TOOLS:
+            assert {"status", "code", "summary", "schema_version"} <= set(props[name]), name
+
+
+class TestBoardInfoTool:
+    def test_default_profile_returns_envelope(self):
+        async def go():
+            return await srv.mcp.call_tool("board_info", {})
+        res = asyncio.run(go())
+        sc = res.structured_content
+        assert res.is_error is False
+        assert sc["schema_version"] == results.SCHEMA_VERSION
+        assert sc["status"] == "succeeded"
+        assert sc["code"] == results.OK
+        assert sc["policy"] == {"risk": "R0"}
+        assert isinstance(sc["data"]["probes"], list)
+
+    def test_missing_profile_is_structured_failure(self):
+        async def go():
+            return await srv.mcp.call_tool(
+                "board_info", {"board": "Z:/definitely/missing.yaml"})
+        res = asyncio.run(go())
+        sc = res.structured_content
+        assert sc["status"] == "failed"
+        assert sc["code"] == results.PROFILE_NOT_FOUND
+        assert res.is_error is False        # domain errors are envelopes, not MCP errors
+
+
+class TestProbeTool:
+    def test_unresolved_serial_is_incomplete_never_pass(self, monkeypatch):
+        monkeypatch.setattr(
+            srv.serialmon, "resolve_console_port",
+            lambda serial_port, vid, pids: (None, "no serial found"))
+        async def go():
+            return await srv.mcp.call_tool("probe", {})
+        res = asyncio.run(go())
+        sc = res.structured_content
+        assert sc["status"] == "incomplete"
+        assert sc["code"] == results.CAPABILITY_UNAVAILABLE
+
+    def test_unopenable_serial_is_incomplete(self, tmp_path, monkeypatch):
+        import serial as serial_mod
+
+        board_yaml = tmp_path / "board.yaml"
+        board_yaml.write_text(
+            "board: t\nmcu: m\ndescription: d\nfirmware:\n  dir: fw\n"
+            "  build: ninja -C build\n  artifact: build/fw.bin\nserial:\n"
+            "  baudrate: 9600\n  banner: 'BOOT {git}'\n", encoding="utf-8")
+        (tmp_path / "fw").mkdir()
+        monkeypatch.setattr(
+            srv.serialmon, "resolve_console_port",
+            lambda serial_port, vid, pids: ("COMX", "hint"))
+
+        def boom(*a, **k):
+            raise serial_mod.SerialException("access denied")
+        monkeypatch.setattr(srv.serialmon, "open_flush", boom)
+        async def go():
+            return await srv.mcp.call_tool("probe", {"board": str(board_yaml)})
+        res = asyncio.run(go())
+        sc = res.structured_content
+        assert sc["status"] == "incomplete"
+        assert sc["code"] == results.TRANSPORT_ERROR
+        assert "COMX" in sc["summary"]
+
+
+class TestProbeEdgeCases:
+    """Regressions from the adversarial review of 0.5.0."""
+
+    @staticmethod
+    def _board_yaml(tmp_path):
+        yaml = tmp_path / "board.yaml"
+        yaml.write_text(
+            "board: t\nmcu: m\ndescription: d\nfirmware:\n  dir: fw\n"
+            "  build: ninja -C build\n  artifact: build/fw.bin\nserial:\n"
+            "  baudrate: 9600\n  banner: 'BOOT {git}'\n", encoding="utf-8")
+        (tmp_path / "fw").mkdir()
+        return yaml
+
+    def test_empty_names_means_all_like_cli(self, tmp_path, monkeypatch):
+        # F1 regression: probe(names=[]) used to run ZERO probes and return
+        # succeeded — a false pass at the heart of the gate's invariant.
+        # [] must behave exactly like None ("all"), as the CLI does.
+        yaml = self._board_yaml(tmp_path)
+        monkeypatch.setattr(srv.serialmon, "resolve_console_port",
+                            lambda sp, vid, pids: ("COMX", "hint"))
+        monkeypatch.setattr(srv.serialmon, "open_flush",
+                            lambda *a, **k: SimpleNamespace(close=lambda: None))
+        called = {}
+        def fake_run(b, names, conn):
+            called["names"] = names
+            return 0
+        monkeypatch.setattr(srv.cli_mod, "_run_probes", fake_run)
+        res = asyncio.run(srv.mcp.call_tool(
+            "probe", {"board": str(yaml), "names": []}))
+        assert res.structured_content["status"] == "succeeded"
+        assert called["names"] is None              # expanded to "all"
+
+    def test_unknown_probe_name_is_invalid_argument(self, tmp_path, monkeypatch):
+        # F3: a typo in probe names is an argument error, not a missing
+        # capability — the agent should fix the name, not hunt the serial.
+        yaml = self._board_yaml(tmp_path)
+        monkeypatch.setattr(srv.serialmon, "resolve_console_port",
+                            lambda sp, vid, pids: (None, "n/a"))
+        res = asyncio.run(srv.mcp.call_tool(
+            "probe", {"board": str(yaml), "names": ["typo"]}))
+        sc = res.structured_content
+        assert sc["status"] == "failed"
+        assert sc["code"] == results.INVALID_ARGUMENT
+        assert "typo" in sc["summary"]
+
+
+class TestCatchAllGuard:
+    def test_internal_exception_becomes_envelope(self, monkeypatch):
+        # F2: no exception may escape a tool into an MCP protocol error;
+        # the envelope contract survives even a crash inside the CLI layer.
+        def boom(b):
+            raise RuntimeError("kaboom")
+        monkeypatch.setattr(srv.cli_mod, "cmd_doctor", boom)
+        res = asyncio.run(srv.mcp.call_tool("doctor", {}))
+        sc = res.structured_content
+        assert res.is_error is False
+        assert sc["status"] == "failed"
+        assert sc["code"] == results.INTERNAL_ERROR
+        assert "kaboom" in sc["summary"]

flashgate-0.4.2/flashgate/mcp_server.py

@@ -1,221 +0,0 @@
-"""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()