enginehall 2.0.0__py3-none-any.whl

pcba/discover.py

@@ -0,0 +1,350 @@
+"""Find the artifacts of an embedded project without being told where they are.
+
+An optional `pcba-studio.toml` selects a target in repositories with several boards or
+revisions. Without it, a pruned walk discovers inputs so `enginehall review` still works on a
+single project with no setup.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import re
+from pathlib import Path
+
+from pcba import config
+from pcba.components import ComponentDataError
+from pcba.model.pinmap import Project
+from pcba.parsers import altium, firmware, kicad
+from pcba.parsers import ioc as ioc_parser
+from pcba.parsers.altium.records import SchDocError
+from pcba.parsers.firmware.index import SKIP_DIRECTORIES as FIRMWARE_SKIP_DIRECTORIES
+from pcba.parsers.ioc import IocError
+from pcba.requirements import RequirementsError
+
+SKIP_DIRECTORIES = frozenset(
+    {".git", "node_modules", "build", "dist", ".venv", "venv", "__pycache__", "archive", "legacy"}
+)
+
+
+def _parts_compatible(config_part: str, schematic_part: str) -> bool:
+    """Compare orderable names, CubeMX variant groups, and its terminal x wildcard."""
+    for variant in ioc_parser.expand_variants(config_part.upper()):
+        pattern = re.escape(variant).replace("X", ".")
+        if re.fullmatch(pattern, schematic_part.upper()):
+            return True
+    return False
+
+
+@dataclasses.dataclass(slots=True)
+class Discovery:
+    """What we found, and what we couldn't."""
+
+    root: Path
+    target: str | None = None
+    schematic_dir: Path | None = None
+    ioc: Path | None = None
+    firmware_roots: list[Path] = dataclasses.field(default_factory=list)
+    part: str | None = None
+    notes: list[str] = dataclasses.field(default_factory=list)
+    kicad_project: Path | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "root": str(self.root),
+            "target": self.target,
+            "schematic_dir": str(self.schematic_dir) if self.schematic_dir else None,
+            "kicad_project": str(self.kicad_project) if self.kicad_project else None,
+            "ioc": str(self.ioc) if self.ioc else None,
+            "firmware_roots": [str(p) for p in self.firmware_roots],
+            "part": self.part,
+            "notes": self.notes,
+        }
+
+
+@dataclasses.dataclass(slots=True)
+class _Scan:
+    schematic_dir: Path | None
+    iocs: list[Path]
+    firmware_roots: list[Path]
+    kicad_projects: list[Path]
+
+
+def _scan_artifacts(root: Path) -> _Scan:
+    """Find schematic, IOC, firmware and KiCad artifacts in one pruned directory walk."""
+    counts: dict[Path, int] = {}
+    iocs: list[Path] = []
+    firmware_roots: list[Path] = []
+    kicad_projects: list[Path] = []
+    kicad_sheets: dict[Path, int] = {}
+
+    for current, directories, files in os.walk(root):
+        directories[:] = sorted(name for name in directories if name not in SKIP_DIRECTORIES)
+        directory = Path(current)
+
+        sheet_count = sum(name.endswith(".SchDoc") for name in files)
+        if sheet_count:
+            counts[directory] = sheet_count
+        iocs.extend(directory / name for name in sorted(files) if name.endswith(".ioc"))
+        kicad_projects.extend(directory / name for name in sorted(files) if name.endswith(".kicad_pro"))
+        kicad_count = sum(name.endswith((".kicad_sch", ".kicad_pcb")) for name in files)
+        if kicad_count:
+            kicad_sheets[directory] = kicad_count
+
+        relative_parts = set(directory.relative_to(root).parts)
+        if FIRMWARE_SKIP_DIRECTORIES & relative_parts:
+            continue
+        if directory.name == "Core" and (directory / "Src").is_dir():
+            firmware_roots.append(directory.parent)
+        elif any(name.endswith(".ioc") for name in files) and _generated_beside_ioc(
+            directory, directories
+        ):
+            firmware_roots.append(directory)
+
+    schematic_dir = max(sorted(counts), key=lambda directory: counts[directory]) if counts else None
+    if not kicad_projects and kicad_sheets:
+        # A KiCad design without its project file: the folder with the most KiCad files.
+        kicad_projects.append(max(sorted(kicad_sheets), key=lambda directory: kicad_sheets[directory]))
+    return _Scan(schematic_dir, sorted(iocs), sorted(set(firmware_roots)), kicad_projects)
+
+
+def _generated_beside_ioc(directory: Path, subdirectories: list[str]) -> bool:
+    """Does CubeMX's generated project sit next to this .ioc without a `Core/` folder?
+
+    Newer CubeMX layouts drop `Core/`: an STM32N6 secure project generates `FSBL/Src` and
+    `Appli/Src` next to the .ioc, a CMake project adds `CMakeLists.txt`. Looking only for
+    `Core/Src` reported such a project as having no firmware at all.
+    """
+    if (directory / "CMakeLists.txt").is_file() or (directory / "Src").is_dir():
+        return True
+    return any((directory / name / "Src").is_dir() for name in subdirectories)
+
+
+
+def _firmware_beside(ioc: Path | None, roots: list[Path], notes: list[str]) -> list[Path]:
+    """Without configuration, keep only the firmware trees that belong to the chosen .ioc.
+
+    A repository holding two boards has two CubeMX trees. Merging both and checking them
+    against one .ioc reports the other board's hard-coded pins as drift, with nothing pointing
+    at the cause. CubeMX generates a project next to its .ioc, so a tree belongs to the .ioc
+    when it sits in the .ioc's directory. With several trees and none there, the pairing is
+    a guess, and the firmware rules do not run rather than run against the wrong board.
+    """
+    if ioc is None or len(roots) <= 1:
+        return roots
+    base = ioc.parent
+    paired = [root for root in roots if root == base or base in root.parents]
+    if paired:
+        if len(paired) < len(roots):
+            notes.append(
+                f"{len(roots)} firmware trees found; using the {len(paired)} beside {ioc.name}. "
+                "Configure firmware_roots in pcba-studio.toml to choose others."
+            )
+        return paired
+    notes.append(
+        f"{len(roots)} firmware trees found and none beside {ioc.name} — firmware rules will "
+        "not run. Configure firmware_roots in pcba-studio.toml."
+    )
+    return []
+
+
+def discover(
+    root: Path,
+    ioc: Path | None = None,
+    schematic_dir: Path | None = None,
+    firmware_roots: tuple[Path, ...] | None = None,
+    kicad_project: Path | None = None,
+) -> Discovery:
+    """Locate a project's artifacts. Explicit overrides replace automatic selection.
+
+    The overrides are taken *here* rather than patched onto the result afterwards. Doing it
+    afterwards left the discovery notes describing the file we no longer use — the tool
+    said "using disco.ioc" while reviewing a different one, which is the kind of small lie
+    that makes an engineer stop trusting the output.
+    """
+    root = Path(root).resolve()
+    found = Discovery(root=root)
+    scan = _scan_artifacts(root)
+    discovered_schematic, discovered_iocs, discovered_firmware = scan.schematic_dir, scan.iocs, scan.firmware_roots
+
+    if kicad_project:
+        found.kicad_project = Path(kicad_project)
+    elif scan.kicad_projects and not schematic_dir:
+        found.kicad_project = scan.kicad_projects[0]
+        if len(scan.kicad_projects) > 1:
+            found.notes.append(
+                f"{len(scan.kicad_projects)} KiCad projects found; using {scan.kicad_projects[0].name}. "
+                "Pass --kicad-project or configure pcba-studio.toml to choose another."
+            )
+
+    found.schematic_dir = Path(schematic_dir) if schematic_dir else discovered_schematic
+    if not found.schematic_dir:
+        if not found.kicad_project:
+            found.notes.append("no .SchDoc sheets or KiCad project found — schematic rules will not run")
+    elif not found.schematic_dir.is_dir():
+        found.notes.append(f"{found.schematic_dir} is not a directory — schematic rules skipped")
+        found.schematic_dir = None
+
+    if ioc:
+        found.ioc = Path(ioc)
+        if not found.ioc.is_file():
+            found.notes.append(f"{found.ioc} not found — MCU-config rules will not run")
+            found.ioc = None
+    else:
+        iocs = discovered_iocs
+        if iocs:
+            found.ioc = iocs[0]
+            if len(iocs) > 1:
+                # Honest about the limitation rather than silently picking one.
+                found.notes.append(
+                    f"{len(iocs)} .ioc files found; using {iocs[0].name}. "
+                    "Pass --ioc or configure pcba-studio.toml to choose another."
+                )
+        else:
+            found.notes.append("no .ioc found — MCU-config rules will not run")
+
+    if firmware_roots is None:
+        found.firmware_roots = _firmware_beside(found.ioc, discovered_firmware, found.notes)
+    else:
+        configured_roots = [Path(item) for item in firmware_roots]
+        found.firmware_roots = [item for item in configured_roots if item.is_dir()]
+        for item in configured_roots:
+            if not item.is_dir():
+                found.notes.append(f"{item} is not a firmware directory — ignored")
+    if not found.firmware_roots and not (firmware_roots is None and discovered_firmware):
+        found.notes.append("no firmware tree found — firmware rules will not run")
+
+    if found.ioc:
+        try:
+            found.part = ioc_parser.part_name(ioc_parser.parse_ioc(found.ioc))
+        except IocError as exc:
+            found.notes.append(f"cannot read {found.ioc.name}: {exc}")
+    if not found.part and found.schematic_dir:
+        found.part = altium.detect_part(found.schematic_dir)
+
+    return found
+
+
+def build_project(
+    found: Discovery, part: str | None = None, component: str | None = None, *, tools: bool = True
+) -> Project:
+    """Parse everything discovery located into the normalized model.
+
+    A parser that fails degrades to `None` with a note. Half a review is useful; a crash
+    because one artifact is missing is not. `tools=False` reads a KiCad project without running
+    kicad-cli or ngspice (what `enginehall inspect` wants).
+    """
+    project = Project(root=str(found.root))
+    project.formats = tuple(name for name, present in (("altium", found.schematic_dir),
+                                                       ("kicad", found.kicad_project)) if present)
+    part = part or found.part
+    if found.kicad_project:
+        try:
+            project.design = kicad.load_design(found.kicad_project, found.root, tools=tools)
+        except (RequirementsError, ComponentDataError) as exc:
+            raise config.ProjectConfigError(str(exc)) from exc
+        found.notes.extend(f"kicad: {note}" for note in project.design.notes)
+        if not part and not found.schematic_dir and project.design.schematic:
+            part = kicad.detect_part(project.design.schematic)
+            found.part = found.part or part
+
+    if found.ioc:
+        try:
+            project.mcu = ioc_parser.load(found.ioc)
+        except IocError as exc:
+            found.notes.append(f"cannot parse {found.ioc.name}: {exc}")
+
+    if found.schematic_dir and part:
+        try:
+            project.schematic = altium.extract(found.schematic_dir, part, component=component)
+        except SchDocError as exc:
+            candidates = altium.detect_parts(found.schematic_dir)
+            matching = [(name, sheet) for name, sheet in candidates
+                        if _parts_compatible(part, name)]
+            selected = matching[0] if len(matching) == 1 else (
+                candidates[0] if len(candidates) == 1 else None
+            )
+            if selected:
+                actual, sheet = selected
+                if project.mcu and project.mcu.part and not _parts_compatible(project.mcu.part, actual):
+                    project.part_conflict = (actual, str(sheet))
+                    found.notes.append(
+                        "schematic MCU differs from CubeMX MCU; pin comparisons were skipped"
+                    )
+                try:
+                    project.schematic = altium.extract(
+                        found.schematic_dir, actual, component=component
+                    )
+                except SchDocError as actual_error:
+                    found.notes.append(f"cannot extract pin map: {actual_error}")
+            else:
+                found.notes.append(f"cannot extract pin map: {exc}")
+                if len(candidates) > 1:
+                    found.notes.append(
+                        "multiple schematic MCU part candidates; select one with --part or a target"
+                    )
+    elif found.schematic_dir and not part:
+        found.notes.append(
+            "schematic found but the MCU part is unknown — pass --part to enable "
+            "schematic and cross-domain rules"
+        )
+
+    kicad_schematic = project.design.schematic if project.design else None
+    if project.schematic is None and kicad_schematic is not None and not found.schematic_dir:
+        _kicad_pin_map(project, found, kicad_schematic, part, component)
+
+    if project.schematic and project.mcu and project.mcu.part and not project.part_conflict:
+        if not _parts_compatible(project.mcu.part, project.schematic.part):
+            sheet = next(iter(project.schematic.pins.values()), None)
+            source = sheet.sheet if sheet else project.schematic.source
+            project.part_conflict = (project.schematic.part, source)
+            found.notes.append("schematic MCU differs from CubeMX MCU; pin comparisons were skipped")
+
+    if found.firmware_roots:
+        try:
+            index = firmware.index(found.firmware_roots[0])
+            # A root inside another (CM4/ under a project root that has Core/Src too) is walked by
+            # both. A file is taken from the first root that reached it, so no reference counts
+            # twice, while a configured root the outer walk skips (one under build/) still counts.
+            files = {os.path.realpath(r.path) for r in index.references}
+            for extra in found.firmware_roots[1:]:
+                references = firmware.index(extra).references
+                index.references.extend(
+                    r for r in references if os.path.realpath(r.path) not in files
+                )
+                files |= {os.path.realpath(r.path) for r in references}
+            project.firmware = index
+        except OSError:
+            found.notes.append("cannot read all firmware sources — firmware rules skipped")
+
+    return project
+
+
+def _kicad_pin_map(project: Project, found: Discovery, schematic, part: str | None, component: str | None) -> None:
+    """The MCU pin map of a KiCad schematic, with the same part fallbacks as the Altium path."""
+    candidates = kicad.detect_parts(schematic)
+    if not part:
+        if not candidates:
+            found.notes.append("the KiCad schematic has no STM32 symbol — MCU pin-map rules will not run")
+            return
+        if len(candidates) > 1:
+            found.notes.append("multiple schematic MCU part candidates; select one with --part or a target")
+            return
+        part = candidates[0][0]
+    try:
+        project.schematic = kicad.extract(schematic, part, component=component)
+        return
+    except kicad.KicadError as exc:
+        matching = [(name, sheet) for name, sheet in candidates if _parts_compatible(part, name)]
+        selected = matching[0] if len(matching) == 1 else (candidates[0] if len(candidates) == 1 else None)
+        if not selected:
+            found.notes.append(f"cannot extract pin map: {exc}")
+            return
+    actual, sheet = selected
+    if project.mcu and project.mcu.part and not _parts_compatible(project.mcu.part, actual):
+        project.part_conflict = (actual, sheet)
+        found.notes.append("schematic MCU differs from CubeMX MCU; pin comparisons were skipped")
+    try:
+        project.schematic = kicad.extract(schematic, actual, component=component)
+    except kicad.KicadError as actual_error:
+        found.notes.append(f"cannot extract pin map: {actual_error}")

pcba/doctor.py

@@ -0,0 +1,131 @@
+"""`enginehall doctor`: what a session needs before it drives Altium Designer or Autodesk Fusion, and
+which optional tools the KiCad review can use (kicad-cli, ngspice).
+
+Each missing piece used to surface one failure at a time, mid-task: `pcba` not on PATH so the
+MCP server never started, a console that could not print UTF-8, no git identity for a commit,
+Altium not running or its bridge not answering, Fusion's MCP endpoint not enabled. One command
+now lists them with the fix. Only Python itself is required; everything else is a warning,
+because a session may need Altium without Fusion or the other way round.
+
+Never on the review path; the Altium checks import the Class C adapter lazily, Windows only.
+"""
+
+from __future__ import annotations
+
+import json
+import locale
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+FUSION_MCP = "http://127.0.0.1:27182/mcp"
+
+
+def _check(check: str, ok: bool, detail: str, fix: str = "", required: bool = False) -> dict:
+    return {"check": check, "ok": bool(ok), "detail": detail, "fix": fix, "required": required}
+
+
+def _git_config(key: str) -> str:
+    try:
+        done = subprocess.run(["git", "config", key], capture_output=True, text=True, check=False)
+    except OSError:
+        return ""
+    return done.stdout.strip()
+
+
+def fusion_endpoint(url: str = FUSION_MCP, timeout: float = 4.0) -> tuple[bool, str]:
+    """Whether Fusion's MCP server answers an MCP initialize (streamable HTTP)."""
+    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                       "params": {"protocolVersion": "2025-06-18", "capabilities": {},
+                                  "clientInfo": {"name": "pcba-doctor"}}}).encode()
+    request = urllib.request.Request(url, data=body, method="POST", headers={
+        "Content-Type": "application/json", "Accept": "application/json, text/event-stream"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as reply:
+            return True, f"answered (HTTP {reply.status}, session {bool(reply.headers.get('Mcp-Session-Id'))})"
+    except urllib.error.HTTPError as exc:
+        return False, f"HTTP {exc.code}"
+    except (urllib.error.URLError, OSError) as exc:
+        return False, str(getattr(exc, "reason", exc))
+
+
+def _altium(ping: bool) -> list[dict]:
+    if sys.platform != "win32":
+        return [_check("altium", False, "Altium Designer runs on Windows only")]
+    from pcba.adapters.altium_drive import DriveError, Session, find_altium
+
+    out = []
+    try:
+        install = find_altium()
+        out.append(_check("altium install", True, f"{install.product} {install.version} ({install.exe})"))
+    except DriveError as exc:
+        return [_check("altium install", False, str(exc), "install Altium Designer (or pass its X2.EXE)")]
+    try:
+        session = Session()
+    except DriveError as exc:
+        return out + [_check("altium bridge", False, str(exc),
+                             "reinstall enginehall: the packaged bridge failed its hash")]
+    out.append(_check("altium bridge", True, f"bridge {session.bridge['version']} installed and verified"))
+    running = session.running()
+    out.append(_check("altium running", running, "running" if running else "not running", "start Altium Designer"))
+    if running and ping:
+        result = session.ping()
+        out.append(_check("altium answers", result["ok"],
+                          f"engine {result['engine']}, bridge {result['bridge']} in {result['seconds']} s",
+                          "enginehall altium call altium_recover (allow_restart only if nothing is unsaved)"))
+    return out
+
+
+def _kicad() -> list[dict]:
+    """kicad-cli (ERC, DRC, netlist cross-check) and ngspice (testbenches): optional for a KiCad
+    review; without them those checks are reported as not checked."""
+    from pcba import simulation
+    from pcba.parsers.kicad import kicad_cli
+
+    cli, how = kicad_cli.find()
+    version = kicad_cli.version(cli) if cli else None
+    checks = [_check("kicad-cli", bool(cli), f"{cli} ({version or 'version unknown'}, {how})" if cli else how,
+                     "install KiCad 9 or 10, or set PCBA_KICAD_CLI to kicad-cli")]
+    spice, how = simulation.find()
+    checks.append(_check("ngspice", bool(spice), f"{spice} ({how})" if spice else how,
+                         "install ngspice (brew install ngspice / apt install ngspice), or set PCBA_NGSPICE"))
+    return checks
+
+
+def run(ping: bool = True) -> list[dict]:
+    checks = [_check("python", sys.version_info >= (3, 11), platform.python_version(), "install Python 3.11 or newer",
+                     required=True)]
+    exe = shutil.which("pcba")
+    checks.append(_check("pcba on PATH", bool(exe), exe or "not found",
+                         "activate the virtualenv, or register the MCP server with the venv's python: "
+                         "codex mcp add pcba-altium -- <absolute-python> -m pcba.cli altium mcp "
+                         "(Claude Code: claude mcp add pcba-altium -- <absolute-python> -m pcba.cli altium mcp)"))
+    uvx = shutil.which("uvx")
+    checks.append(_check("uvx", bool(uvx), uvx or "not found",
+                         "install uv (https://docs.astral.sh/uv/): the EngineHall Claude Code plugin starts "
+                         "enginehall mcp and enginehall altium mcp with uvx"))
+    # pcba itself writes UTF-8 (cli._utf8_console); this is what other Python tools on this machine get.
+    encoding = (os.environ.get("PYTHONIOENCODING")
+                or ("utf-8" if sys.flags.utf8_mode or os.environ.get("PYTHONUTF8") == "1"
+                    else locale.getpreferredencoding(False))
+                or "").lower().split(":")[0]
+    checks.append(_check("console encoding", encoding in ("utf-8", "utf8"), encoding or "unknown",
+                         "set PYTHONIOENCODING=utf-8 (or PYTHONUTF8=1) for other Python tools"))
+    if shutil.which("git"):
+        name, email = _git_config("user.name"), _git_config("user.email")
+        checks.append(_check("git identity", bool(name and email), f"{name or '?'} <{email or '?'}>",
+                             "git config user.name/user.email, or git -c user.name=... -c user.email=... commit"))
+    else:
+        checks.append(_check("git", False, "not found", "install git"))
+    checks += _kicad()
+    checks += _altium(ping)
+    ok, detail = fusion_endpoint()
+    checks.append(_check("fusion mcp", ok, detail,
+                         "start Fusion, enable Preferences > General > API > MCP server, then: claude mcp add "
+                         f"--transport http fusion {FUSION_MCP} "
+                         f"(Codex: codex mcp add fusion --url {FUSION_MCP})"))
+    return checks

pcba/house.py

@@ -0,0 +1,123 @@
+"""Newmatik house DFM values, shared by every board format.
+
+The Altium drive (`pcba/adapters/altium_house.py`, Class C) and the KiCad board rules
+(`pcba/rules/kicad_board.py`, on the review path) check the same house requirements. The values
+live here, in a module both may import, so the two can never disagree about a number; the
+finding ids (`NM-FID-001` ...) name the same requirement in both.
+
+Values marked ``proposed`` are starting points until Newmatik process engineering confirms
+them; `status()` in the Altium module and the KiCad findings quote that status. Nothing here
+claims manufacturability: the checks report.
+"""
+
+from __future__ import annotations
+
+import math
+
+HOUSE = "Newmatik house DFM"
+VERSION = "1"
+
+# Fiducial policy. The count is a Newmatik requirement (2026-10-05); the geometry is the global
+# fiducial class Newmatik already uses (1.0 mm copper, 3.0 mm solder-mask opening, no paste).
+FIDUCIALS = {
+    "per_smd_side": 3,
+    "copper_mm": 1.0,
+    "copper_tolerance_mm": 0.05,
+    "mask_opening_mm": 3.0,
+    "mask_tolerance_mm": 0.1,
+    "edge_min_mm": 3.0,          # proposed: centre to board edge
+    "min_angle_deg": 15.0,       # proposed: the three must form a real triangle
+    "min_spread": 0.5,           # proposed: span at least half the board in x and in y
+}
+FIDUCIAL_STATUS = {"per_smd_side": "required", "copper_mm": "house", "mask_opening_mm": "house"}
+
+# What review found one correction at a time on the first boards built with the drive, and what
+# a CAD tool's DRC does not check.
+LAYOUT = {
+    "silk_tolerance_mm": 0.01,       # silkscreen beyond the outline by more than this is lost
+    "track_angle_step_deg": 45.0,    # copper tracks at 0, 45, 90 or 135 degrees
+    "track_angle_tolerance_deg": 0.5,
+    "same_net_via_min_mm": 2.0,      # proposed: closer same-net vias could be one via
+    "join_tolerance_mm": 0.01,       # track ends this close to a joint but not on it are near misses
+    "barcode_min_mm": 5.0,           # a square silkscreen field with "BC" for the serial label
+    "barcode_preferred_mm": 7.0,
+}
+LAYOUT_STATUS = {"silk_tolerance_mm": "house", "track_angle_step_deg": "house", "same_net_via_min_mm": "proposed",
+                 "join_tolerance_mm": "house",
+                 "barcode_min_mm": "house", "barcode_preferred_mm": "house"}
+
+
+def fiducial_status(key: str) -> str:
+    return FIDUCIAL_STATUS.get(key, "proposed")
+
+
+def layout_status(key: str) -> str:
+    return LAYOUT_STATUS.get(key, "proposed")
+
+
+# --- plane geometry (mm) ------------------------------------------------------------------------
+
+
+def angles(a, b, c) -> list[float]:
+    """The three inner angles (degrees) of the triangle a, b, c."""
+    def angle(p, q, r):
+        v1 = (q[0] - p[0], q[1] - p[1])
+        v2 = (r[0] - p[0], r[1] - p[1])
+        n = math.hypot(*v1) * math.hypot(*v2)
+        if n == 0:
+            return 0.0
+        cos = max(-1.0, min(1.0, (v1[0] * v2[0] + v1[1] * v2[1]) / n))
+        return math.degrees(math.acos(cos))
+    return [angle(a, b, c), angle(b, c, a), angle(c, a, b)]
+
+
+def inside(point, outline) -> bool:
+    """Ray casting: whether the point lies inside the outline polygon."""
+    x, y = point
+    result = False
+    for (x1, y1), (x2, y2) in zip(outline, outline[1:] + outline[:1]):
+        if (y1 > y) != (y2 > y) and x < (x2 - x1) * (y - y1) / (y2 - y1) + x1:
+            result = not result
+    return result
+
+
+def edge_distance(point, outline) -> float:
+    """Distance from a point to the nearest edge of the outline polygon."""
+    best = math.inf
+    for (x1, y1), (x2, y2) in zip(outline, outline[1:] + outline[:1]):
+        best = min(best, segment_distance(point, (x1, y1), (x2, y2)))
+    return best
+
+
+def segment_distance(point, a, b) -> float:
+    (x1, y1), (x2, y2) = a, b
+    dx, dy = x2 - x1, y2 - y1
+    length = dx * dx + dy * dy
+    t = 0.0 if length == 0 else max(0.0, min(1.0, ((point[0] - x1) * dx + (point[1] - y1) * dy) / length))
+    return math.hypot(x1 + t * dx - point[0], y1 + t * dy - point[1])
+
+
+def inside_segments(point, segments) -> bool:
+    """Even-odd ray casting over unordered edges, so an outline with cut-outs works too."""
+    x, y = point
+    result = False
+    for (x1, y1), (x2, y2) in segments:
+        if (y1 > y) != (y2 > y) and x < (x2 - x1) * (y - y1) / (y2 - y1) + x1:
+            result = not result
+    return result
+
+
+def edge_distance_segments(point, segments) -> float:
+    return min((segment_distance(point, a, b) for a, b in segments), default=math.inf)
+
+
+def distance_to_pad(x: float, y: float, pad: dict) -> float:
+    """Distance from a point to a pad's copper, the pad taken as its (rotated) rectangle; a round
+    pad as its circle. `pad` has x, y, w, h, shape and rotation (degrees)."""
+    dx, dy = x - pad["x"], y - pad["y"]
+    if pad.get("shape") in ("round", "circle") and abs(pad["w"] - pad["h"]) < 1e-6:
+        return max(0.0, math.hypot(dx, dy) - pad["w"] / 2)
+    a = math.radians(-(pad.get("rotation") or 0))
+    lx, ly = dx * math.cos(a) - dy * math.sin(a), dx * math.sin(a) + dy * math.cos(a)
+    ox, oy = max(0.0, abs(lx) - pad["w"] / 2), max(0.0, abs(ly) - pad["h"] / 2)
+    return math.hypot(ox, oy)

pcba/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server exposing the engine to agents."""
+
+from pcba.mcp.server import TOOLS, handle, serve
+
+__all__ = ["TOOLS", "handle", "serve"]