enginehall 2.0.0__py3-none-any.whl

pcba/cli.py

@@ -0,0 +1,891 @@
+"""The `enginehall` command, also installed as `hall` and, deprecated, as `pcba`.
+
+The distribution is `enginehall`; the import package stays `pcba` (a module rename would touch
+every import, test and adapter for no user-visible gain).
+
+Exit codes are part of the contract, because CI reads them:
+    0  clean
+    1  findings at or above the failure threshold
+    2  could not run (bad input, missing tool, unreadable file)
+
+Note `cubemx diff` returning 1 on any difference. The tool this replaces always returned 0,
+so it could never gate anything — while its own documentation told you to run it after every
+code generation. A check that cannot fail is decoration.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import traceback
+from pathlib import Path
+
+from pcba import __version__, baseline, changes, config, publish, review
+from pcba.model.finding import Severity
+from pcba.model.pinmap import is_power_pin, port_sort_key
+from pcba.parsers import altium
+from pcba.parsers import ioc as ioc_parser
+from pcba.parsers.altium.records import SchDocError
+from pcba.parsers.ioc import IocError
+from pcba.parsers.kicad import KicadError, SexprError
+
+EXIT_OK, EXIT_FINDINGS, EXIT_ERROR = 0, 1, 2
+
+
+# --- review ----------------------------------------------------------------------------
+
+
+def _publish_target(args) -> publish.Target | None:
+    """The publish destination, checked before the review runs; None without --publish."""
+    if not args.publish:
+        named = [flag for flag, value in (("--project", args.project), ("--url", args.url),
+                                          ("--token-env", args.token_env), ("--commit", args.commit),
+                                          ("--repository", args.repository)) if value]
+        if named:
+            raise publish.PublishError(f"{', '.join(named)} needs --publish")
+        return None
+    return publish.target(args.project, args.url, args.token_env, args.commit,
+                          repository=args.repository, root=Path(args.path))
+
+
+def cmd_review(args) -> int:
+    destination = _publish_target(args)
+    result = review.run(
+        args.path,
+        part=args.part,
+        ioc=args.ioc,
+        schematic_dir=args.schematic_dir,
+        schematic_component=args.schematic_component,
+        required_rules=tuple(args.require_rule),
+        baseline=args.baseline,
+        changed_only=args.changed_only,
+        target=args.target,
+        kicad_project=args.kicad_project,
+    )
+    findings = result.findings
+    coverage = result.coverage
+    if args.format == "text":
+        for note in result.discovery.notes:
+            print(f"note: {note}", file=sys.stderr)
+    print(result.render(args.format))
+
+    if destination is not None:
+        # After the report is printed, and also when coverage is unmet: CI keeps its output either way.
+        sys.stdout.flush()
+        answer = publish.publish(result, destination)
+        print(f"published: {answer.get('url') or answer['id']}", file=sys.stderr)
+        if destination.repository and "repositoryNotMatched" in (answer.get("warnings") or []):
+            print("note: the repository matches none connected to the project; the check run has no repository",
+                  file=sys.stderr)
+
+    if coverage.get("unmet"):
+        print("error: required checks were not covered: " + ", ".join(coverage["unmet"]), file=sys.stderr)
+        return EXIT_ERROR
+    threshold = Severity(args.fail_on)
+    order = {Severity.ERROR: 0, Severity.WARNING: 1, Severity.INFO: 2}
+    hit = [f for f in findings if order[f.severity] <= order[threshold]]
+    return EXIT_FINDINGS if hit else EXIT_OK
+
+
+def cmd_baseline(args) -> int:
+    result = review.run(
+        args.path,
+        part=args.part,
+        ioc=args.ioc,
+        schematic_dir=args.schematic_dir,
+        schematic_component=args.schematic_component,
+        target=args.target,
+        kicad_project=args.kicad_project,
+    )
+    output = args.output or Path(args.path) / ".pcba-baseline.json"
+    target = baseline.write(output, result.findings, reason=args.reason)
+    print(f"wrote {target} with {len(result.findings)} suppressions")
+    return EXIT_OK
+
+
+# --- inspect ---------------------------------------------------------------------------
+
+
+def cmd_inspect(args) -> int:
+    found, project = review.load_project(
+        args.path,
+        part=args.part,
+        ioc=args.ioc,
+        schematic_dir=args.schematic_dir,
+        schematic_component=args.schematic_component,
+        target=args.target,
+        kicad_project=args.kicad_project,
+        tools=False,
+    )
+    if args.format == "json":
+        print(json.dumps(review.summary(found, project), indent=2))
+        return EXIT_OK
+
+    print(f"project      {found.root}")
+    if found.target:
+        print(f"target       {found.target}")
+    print(f"part         {found.part or '(unknown)'}")
+    if found.schematic_dir or not found.kicad_project:
+        print(f"schematic    {found.schematic_dir or '(none found)'}")
+    if found.kicad_project:
+        design = project.design
+        print(f"kicad        {found.kicad_project}")
+        if design is not None:
+            schematic = design.schematic
+            print(f"  sheets     {len(schematic.sheet_files) if schematic else 0}, "
+                  f"{len([c for c in schematic.components.values() if not c.power]) if schematic else 0} parts, "
+                  f"{len(schematic.nets) if schematic else 0} nets")
+            print(f"  board      {design.board.path if design.board else '(none found)'}")
+            requirements = design.requirements
+            promises = requirements.path if requirements and requirements.path else "(no pcba-requirements.toml)"
+            print(f"  promises   {promises}")
+    print(f"mcu config   {found.ioc or '(none found)'}")
+    for i, root in enumerate(found.firmware_roots):
+        print(f"firmware     {root}" if i == 0 else f"             {root}")
+    if not found.firmware_roots:
+        print("firmware     (none found)")
+    for note in found.notes:
+        print(f"note         {note}")
+    coverage = review.summary(found, project)["coverage"]
+    total = len(coverage["ran"]) + len(coverage["skipped"])
+    print(f"rules        {len(coverage['ran'])} of {total} can run")
+    for skipped in coverage["skipped"]:
+        print(f"cannot run   {skipped}")
+    return EXIT_OK
+
+
+# --- cubemx ----------------------------------------------------------------------------
+
+
+def cmd_cubemx(args) -> int:
+    # Class C: imported here, by the one command that drives CubeMX, so that no other command
+    # (enginehall review above all) loads an adapter.
+    from pcba.adapters.cubemx_drive import DriveError
+
+    try:
+        return _cubemx(args)
+    except DriveError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+def _cubemx(args) -> int:
+    if args.cubemx_command == "drive":
+        from pcba.adapters.cubemx_drive import DriveError
+
+        raise DriveError(
+            "unrestricted CubeMX writes are disabled until a verified change-plan workflow exists; "
+            "use CubeMX directly, or enginehall cubemx roundtrip for an isolated copy"
+        )
+
+    if args.cubemx_command == "roundtrip":
+        # Load and re-save through CubeMX, then diff. If CubeMX rewrites anything, the file
+        # was not canonical — the usual cause is a hand-edit. This is the check that
+        # enforces "the .ioc is CubeMX-owned".
+        #
+        # The predecessor implemented this as a plain subprocess call, which is precisely
+        # the invocation its own documentation explains at length cannot work: no
+        # WindowServer, so it blocks at 0% CPU until the timeout. It goes through the
+        # adapter now, and inherits the adapter's honest macOS-only ceiling.
+        import shutil
+        import tempfile
+
+        from pcba.adapters.cubemx_drive import drive, make_script
+
+        with tempfile.TemporaryDirectory(prefix="pcba-roundtrip-") as tmp:
+            work = Path(tmp) / args.ioc.name
+            shutil.copy2(args.ioc, work)
+            script = Path(tmp) / "roundtrip.mx"
+            script.write_text(make_script(config=work), encoding="utf-8")
+            result = drive(script=script, expect=work, timeout=args.timeout, app=args.app)
+            if not result.ok:
+                raise IocError(result.detail)
+            delta = ioc_parser.diff(ioc_parser.parse_ioc(args.ioc), ioc_parser.parse_ioc(work))
+
+        if args.format == "json":
+            print(json.dumps(delta, indent=2))
+        elif not any(delta.values()):
+            print("canonical: CubeMX re-saved the .ioc unchanged")
+        else:
+            print("CubeMX rewrote the .ioc — it was not canonical (usually a hand-edit):")
+            for key in delta["removed"]:
+                print(f"- {key}")
+            for key in delta["added"]:
+                print(f"+ {key}")
+            for key in delta["changed"]:
+                print(f"~ {key}")
+        return EXIT_FINDINGS if any(delta.values()) else EXIT_OK
+
+    if args.cubemx_command == "diff":
+        before, after = ioc_parser.parse_ioc(args.old), ioc_parser.parse_ioc(args.new)
+        delta = ioc_parser.diff(before, after)
+        if args.format == "json":
+            print(json.dumps(delta, indent=2))
+        else:
+            for key in delta["removed"]:
+                print(f"- {key} = {before[key]}")
+            for key in delta["added"]:
+                print(f"+ {key} = {after[key]}")
+            for key in delta["changed"]:
+                print(f"~ {key}: {before[key]} -> {after[key]}")
+            if not any(delta.values()):
+                print("identical")
+        # Non-zero on any difference — this is the whole point of the subcommand.
+        return EXIT_FINDINGS if any(delta.values()) else EXIT_OK
+
+    values = ioc_parser.parse_ioc(args.ioc)
+
+    if args.cubemx_command == "pins":
+        pins = ioc_parser.collect_pins(values)
+        if args.format == "json":
+            print(json.dumps(pins, indent=2, sort_keys=True))
+            return EXIT_OK
+        if not pins:
+            print("no pins assigned")
+            return EXIT_OK
+        width = max(len(p) for p in pins)
+        for pin in sorted(pins, key=port_sort_key):
+            fields = pins[pin]
+            signal = fields.get("Signal", fields.get("Mode", "-"))
+            label = fields.get("GPIO_Label", "")
+            print(f"{pin:<{width}}  {signal:<28} {label}")
+        return EXIT_OK
+
+    if args.cubemx_command == "peripherals":
+        found = ioc_parser.peripherals(values)
+        print(json.dumps(found, indent=2) if args.format == "json" else "\n".join(found))
+        return EXIT_OK
+
+    if args.cubemx_command == "clocks":
+        found = ioc_parser.clocks(values)
+        if args.format == "json":
+            print(json.dumps(found, indent=2))
+        else:
+            for key, value in found.items():
+                print(f"{key} = {value}")
+        return EXIT_OK
+
+    if args.cubemx_command == "get":
+        hit = {
+            k: v for k, v in sorted(values.items()) if any(k.startswith(w) for w in args.keys)
+        }
+        if args.format == "json":
+            print(json.dumps(hit, indent=2))
+        else:
+            for key, value in hit.items():
+                print(f"{key} = {value}")
+        return EXIT_OK if hit else EXIT_FINDINGS
+
+    if args.cubemx_command in {"af", "free"}:
+        db = ioc_parser.find_mcu_db(Path(args.db) if args.db else None)
+        part = ioc_parser.part_name(values)
+        xml = ioc_parser.resolve_part_xml(db, part, values.get("Mcu.Name"))
+        if args.cubemx_command == "af":
+            pin = args.pin.upper()
+            signals = list(ioc_parser.pin_signals(xml, pin))
+            if not signals:
+                raise IocError(f"{pin} not found in {xml.name}")
+            current = ioc_parser.collect_pins(values).get(pin, {})
+            if args.format == "json":
+                print(
+                    json.dumps(
+                        {
+                            "pin": pin,
+                            "part": part,
+                            "database": xml.name,
+                            "current": current or None,
+                            "can_carry": signals,
+                        },
+                        indent=2,
+                    )
+                )
+                return EXIT_OK
+            print(f"# {pin} on {part}  ({xml.name})")
+            print(
+                f"# currently: {current.get('Signal', '-')}  {current.get('GPIO_Label', '')}"
+                if current
+                else "# currently: unassigned"
+            )
+            print("# can carry:")
+            for signal in signals:
+                print(f"  {signal}")
+            return EXIT_OK
+        unused = sorted(
+            ioc_parser.part_peripherals(str(xml)) - set(ioc_parser.peripherals(values))
+        )
+        if args.format == "json":
+            print(json.dumps({"part": part, "database": xml.name, "unused": unused}, indent=2))
+            return EXIT_OK
+        print(f"# part: {part}  ({xml.name})")
+        print("# peripherals present on the silicon but NOT enabled in this project:")
+        for name in unused:
+            print(f"  {name}")
+        return EXIT_OK
+
+    if args.cubemx_command == "validate":
+        manifest = ioc_parser.load_manifest(args.manifest)
+        errors = ioc_parser.validate(values, manifest)
+        if args.format == "json":
+            print(json.dumps({"passed": not errors, "errors": errors}, indent=2))
+            return EXIT_FINDINGS if errors else EXIT_OK
+        if errors:
+            print("ioc validation failed:", file=sys.stderr)
+            for error in errors:
+                print(f"- {error}", file=sys.stderr)
+            return EXIT_FINDINGS
+        print(f"ioc validation passed: {Path(args.manifest).name}")
+        return EXIT_OK
+
+    return EXIT_ERROR
+
+
+# --- altium ----------------------------------------------------------------------------
+
+
+def cmd_altium(args) -> int:
+    if args.altium_command == "project-sheets":
+        from pcba.parsers.altium import project
+
+        data = project.to_dict(project.read_project(args.project))
+        if args.format == "json":
+            print(json.dumps(data, indent=2))
+        else:
+            print(f"# project sheets of {data['project']}: structural instances only")
+            for instance in data["instances"]:
+                print(" / ".join(instance["path"]) + " -> " + instance["sheet"])
+        return EXIT_OK
+    if args.altium_command == "netlist":
+        return cmd_altium_netlist(args)
+    if args.altium_command == "mcp":
+        # Class C: drives Altium Designer. Imported lazily so nothing on the review path
+        # loads the adapter.
+        from pcba.mcp.altium_server import serve
+
+        serve()
+        return EXIT_OK
+    if args.altium_command == "house-rules":
+        # Pure data and text: needs neither Windows nor Altium.
+        from pcba.adapters import altium_house
+
+        if args.format == "json":
+            print(json.dumps(altium_house.status(), indent=2))
+            return EXIT_OK
+        if args.out:
+            Path(args.out).write_bytes(altium_house.rul_bytes())
+            print(f"wrote {args.out}: {len(altium_house.HOUSE_RULES)} rules, "
+                  f"{altium_house.HOUSE} v{altium_house.VERSION}")
+        else:
+            sys.stdout.write(altium_house.rul_text())
+        return EXIT_OK
+    if args.altium_command == "status":
+        from pcba.adapters.altium_drive import DriveError, Session
+
+        try:
+            print(json.dumps(Session().status(), indent=2))
+        except DriveError as exc:
+            print(json.dumps({"error": exc.to_dict()}, indent=2))
+            return EXIT_ERROR
+        return EXIT_OK
+    if args.altium_command == "call":
+        return cmd_altium_call(args)
+    if args.altium_command == "apply":
+        return cmd_altium_apply(args)
+    if args.altium_command == "remanifest":
+        from pcba.adapters.altium_drive import remanifest
+
+        print(json.dumps(remanifest(), indent=2))
+        return EXIT_OK
+    directory = Path(args.dir)
+    part = args.part or altium.detect_part(directory)
+    if not part:
+        raise SchDocError(f"could not detect an MCU part under {directory}; pass --part")
+
+    pin_map = altium.extract(directory, part, component=args.schematic_component)
+    if args.format == "json":
+        print(json.dumps(altium.to_dict(pin_map), indent=2))
+        return EXIT_OK
+
+    signal = [p for p in pin_map.pins.values() if not is_power_pin(p.name)]
+    print(f"# {part} pin map — extracted from {directory}")
+    print(f"# {len(pin_map.pins)} pins recovered ({len(signal)} signal)")
+    print()
+    for pin in sorted(signal, key=lambda p: port_sort_key(p.port_pin)):
+        print(f"{pin.package_pin:>4}  {pin.port_pin:<7} {pin.net or '—':<32} {pin.resolution}")
+    return EXIT_OK
+
+
+# --- kicad -----------------------------------------------------------------------------
+
+
+def cmd_kicad(args) -> int:
+    from pcba.parsers import kicad
+
+    if args.kicad_command == "netlist":
+        from pcba.parsers.kicad import schematic as reader
+
+        schematic = reader.read(Path(args.project))
+        data = {
+            "root": schematic.root_file,
+            "sheets": schematic.sheet_paths,
+            "nets": {net.name: [[p.ref, p.number] for p in net.parts] for net in schematic.nets},
+            "components": {c.ref: {"value": c.value, "lib_id": c.lib_id, "footprint": c.footprint,
+                                   "sheet": c.sheet_path, "dnp": c.dnp}
+                           for c in schematic.components.values() if not c.power},
+            "notes": schematic.notes,
+        }
+        if args.format == "json":
+            print(json.dumps(data, indent=2))
+            return EXIT_OK
+        print(f"# netlist of {schematic.root_file}: {len(data['nets'])} nets, {len(data['components'])} parts")
+        for name, nodes in data["nets"].items():
+            print(f"{name:<28} " + " ".join(f"{ref}.{pin}" for ref, pin in nodes))
+        for note in schematic.notes:
+            print(f"# note: {note}")
+        return EXIT_OK
+    if args.kicad_command == "pinmap":
+        from pcba.parsers.kicad import schematic as reader
+
+        schematic = reader.read(Path(args.project))
+        part = args.part or kicad.detect_part(schematic)
+        if not part:
+            raise kicad.KicadError(f"no STM32 symbol in {args.project}; pass --part")
+        pin_map = kicad.extract(schematic, part, component=args.schematic_component)
+        if args.format == "json":
+            print(json.dumps(altium.to_dict(pin_map), indent=2))
+            return EXIT_OK
+        print(f"# {part} pin map — extracted from {schematic.root_file}")
+        for pin in sorted(pin_map.pins.values(), key=lambda p: port_sort_key(p.port_pin)):
+            print(f"{pin.package_pin:>4}  {pin.name:<10} {pin.net or '—':<32} {pin.resolution}")
+        return EXIT_OK
+    if args.kicad_command == "board":
+        from pcba.parsers.kicad import board as reader
+
+        path = Path(args.project)
+        if path.is_dir():
+            project_file, root = kicad.find_root(path)
+            path = kicad.board_file(project_file, root) or next(iter(sorted(path.glob("*.kicad_pcb"))), path)
+        board = reader.read(path)
+        data = {
+            "board": board.path, "version": board.version, "nets": len(board.nets),
+            "footprints": [{"ref": f.ref, "lib": f.lib, "side": f.side, "x": f.x, "y": f.y, "rotation": f.rotation,
+                            "pads": len(f.pads), "models": f.models} for f in board.footprints],
+            "tracks": len(board.tracks), "vias": len(board.vias), "zones": len(board.zones),
+            "outline_edges": len(board.outline),
+        }
+        if args.format == "json":
+            print(json.dumps(data, indent=2))
+            return EXIT_OK
+        print(f"# {board.path} (format {board.version}): {len(board.footprints)} footprints, {data['nets']} nets, "
+              f"{data['tracks']} tracks, {data['vias']} vias, {data['zones']} zones, {data['outline_edges']} edges")
+        for f in data["footprints"]:
+            print(f"{f['ref']:<8} {f['side']:<6} {f['lib']}")
+        return EXIT_OK
+    return EXIT_ERROR
+
+
+def _json_arg(value: str | None, name: str):
+    """A JSON argument given inline or as @file.json. A file avoids shell quoting entirely: a
+    Windows path or a backslash in an inline argument is where scripted calls broke."""
+    if value is None:
+        return None
+    text = Path(value[1:]).read_text(encoding="utf-8-sig") if value.startswith("@") else value
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise OSError(f"{name} is not valid JSON ({exc}); pass @file.json to avoid shell quoting") from None
+
+
+def _emit(payload, out: str | None) -> None:
+    """Print a reply, or write it to `out` and print where (a reply can be megabytes)."""
+    text = json.dumps(payload, indent=2, ensure_ascii=False)
+    if out:
+        Path(out).write_text(text + "\n", encoding="utf-8")
+        print(json.dumps({"written": out, "bytes": len(text.encode("utf-8"))}))
+    else:
+        print(text)
+
+
+def _altium_in_band(function, *args, **kwargs) -> dict:
+    """Run an Altium drive tool and answer a failure in band, exactly as `enginehall altium mcp` does."""
+    from pcba.adapters.altium_drive import DriveError
+    from pcba.mcp import altium_server
+
+    try:
+        return function(*args, **kwargs)
+    except DriveError as exc:
+        return {"error": exc.to_dict()}
+    except altium_server.IN_BAND as exc:
+        return {"error": str(exc)}
+
+
+def cmd_altium_call(args) -> int:
+    """Call one `enginehall altium mcp` tool in this process: the same functions the server runs, without
+    an MCP client. Plans are kept on disk, so a plan made here can be applied by the server."""
+    from pcba.mcp import altium_server
+
+    if args.tool not in altium_server.TOOLS:
+        print(f"error: unknown tool {args.tool}; tools: {', '.join(sorted(altium_server.TOOLS))}", file=sys.stderr)
+        return EXIT_ERROR
+    arguments = _json_arg(args.args, "--args") or {}
+    if not isinstance(arguments, dict):
+        print("error: --args must be a JSON object", file=sys.stderr)
+        return EXIT_ERROR
+    function, spec = altium_server.TOOLS[args.tool]
+    unknown = sorted(set(arguments) - set(spec["inputSchema"]["properties"]))
+    if unknown:
+        print(f"error: {args.tool} takes {sorted(spec['inputSchema']['properties'])}; not {unknown}", file=sys.stderr)
+        return EXIT_ERROR
+    payload = _altium_in_band(function, **arguments)
+    _emit(payload, args.out)
+    return EXIT_ERROR if isinstance(payload, dict) and "error" in payload else EXIT_OK
+
+
+def cmd_altium_apply(args) -> int:
+    """Plan typed operations from a file, print the preview, and apply only with --yes (the person
+    running the command approves it). Without --yes the plan stays on disk for altium_apply."""
+    from pcba.mcp import altium_server
+
+    ops = _json_arg(args.ops, "--ops")
+    if not isinstance(ops, list):
+        print("error: --ops must be a JSON list of operations (or @ops.json)", file=sys.stderr)
+        return EXIT_ERROR
+    plan = _altium_in_band(altium_server.tool_plan, ops, args.summary, project=args.project,
+                           sheets_dir=args.sheets_dir, expect_nets=_json_arg(args.expect_nets, "--expect-nets"),
+                           allow_destructive=args.allow_destructive)
+    if "error" in plan:
+        _emit(plan, args.out)
+        return EXIT_ERROR
+    if not args.yes:
+        _emit({**plan, "next": f"apply with --yes, or altium_apply plan_id {plan['plan_id']} hash {plan['hash']}"},
+              args.out)
+        return EXIT_OK
+    result = _altium_in_band(altium_server.tool_apply, plan["plan_id"], plan["hash"])
+    _emit({"plan": plan, **result}, args.out)
+    if "error" in result:
+        return EXIT_ERROR
+    applied = result.get("applied", {})
+    verified = (result.get("verification") or {}).get("match", True)
+    return EXIT_OK if applied.get("ok") and verified else EXIT_ERROR
+
+
+def cmd_doctor(args) -> int:
+    """What a session needs before it drives Altium or Fusion, checked in one place."""
+    from pcba import doctor
+
+    checks = doctor.run(ping=not args.no_ping)
+    if args.format == "json":
+        print(json.dumps(checks, indent=2))
+    else:
+        for c in checks:
+            mark = "ok  " if c["ok"] else ("warn" if not c.get("required") else "FAIL")
+            print(f"{mark} {c['check']:<22} {c['detail']}")
+            if not c["ok"] and c.get("fix"):
+                print(f"     {'':<22} fix: {c['fix']}")
+    return EXIT_OK if all(c["ok"] for c in checks if c.get("required")) else EXIT_FINDINGS
+
+
+def cmd_altium_netlist(args) -> int:
+    from pcba.parsers.altium import netlist
+
+    result = netlist.extract_netlist(Path(args.dir))
+    data = netlist.to_dict(result)
+    if args.format == "json":
+        print(json.dumps(data, indent=2))
+        return EXIT_OK
+    print(f"# netlist of {args.dir}: {len(data['nets'])} nets, {len(data['components'])} components")
+    for name, nodes in data["nets"].items():
+        print(f"{name:<24} " + " ".join(f"{d}.{p}" for d, p in nodes))
+    if data["unconnected"]:
+        print(f"# {len(data['unconnected'])} unconnected pins")
+    for conflict in data["conflicts"]:
+        print(f"# name conflict: {conflict}")
+    return EXIT_OK
+
+
+# --- mcp -------------------------------------------------------------------------------
+
+
+def cmd_mcp(args) -> int:
+    from pcba.mcp.server import serve
+
+    serve()
+    return EXIT_OK
+
+
+# --- wiring ----------------------------------------------------------------------------
+
+
+COMMANDS = ("enginehall", "hall", "pcba")
+DEPRECATION = "note: `pcba` is deprecated and will be removed in EngineHall 3; use `enginehall` (or `hall`)"
+
+
+def build_parser(prog: str = "enginehall") -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description="EngineHall: where hardware gets built, checked and released, together. "
+                    "This command checks that your schematic, your CubeMX configuration and your firmware agree.",
+    )
+    parser.add_argument("--version", action="version", version=f"enginehall {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_format(p, choices=("text", "json")):
+        p.add_argument("--format", choices=choices, default=choices[0])
+
+    review = sub.add_parser("review", help="run every rule over a project")
+    review.add_argument("path", nargs="?", default=".", type=Path)
+    review.add_argument("--part", help="MCU part number (default: auto-detect)")
+    review.add_argument("--ioc", help="path to the .ioc (default: auto-detect)")
+    review.add_argument("--schematic-dir", help="directory of .SchDoc sheets")
+    review.add_argument("--schematic-component", help="MCU designator when a sheet set has several MCU instances")
+    review.add_argument("--kicad-project", help="KiCad project (.kicad_pro or its folder; default: auto-detect)")
+    review.add_argument("--require-rule", action="append", default=[], help="require coverage of RULE_ID; repeatable")
+    review.add_argument("--baseline", help="versioned finding-suppression file")
+    review.add_argument("--target", help=f"target name from {config.CONFIG_NAME}")
+    review.add_argument(
+        "--changed-only",
+        nargs="?",
+        const="HEAD",
+        metavar="REF",
+        help="report findings touching files changed since REF (default: HEAD)",
+    )
+    review.add_argument(
+        "--fail-on",
+        choices=[str(s) for s in Severity],
+        default="error",
+        help="minimum severity that makes the exit code non-zero (default: error)",
+    )
+    review.add_argument("--publish", action="store_true",
+                        help="publish the report (findings, locations, coverage; never files) to a development project")
+    review.add_argument("--project", metavar="KEY", help="development project key, with --publish")
+    review.add_argument("--url", help="workspace origin, with --publish (e.g. https://enginehall.com)")
+    review.add_argument("--token-env", metavar="NAME",
+                        help=f"environment variable holding the project token (default: {publish.DEFAULT_TOKEN_ENV})")
+    review.add_argument("--commit", metavar="SHA",
+                        help="commit the report belongs to (default: $GITHUB_SHA, else git rev-parse HEAD)")
+    review.add_argument("--repository", metavar="ID_OR_URL",
+                        help="repository of the project the commit is in (default: the origin remote's URL)")
+    add_format(review, ("text", "json", "sarif", "markdown"))
+    review.set_defaults(func=cmd_review)
+
+    baseline_parser = sub.add_parser("baseline", help="write suppressions for current findings")
+    baseline_parser.add_argument("path", nargs="?", default=".", type=Path)
+    baseline_parser.add_argument("--part", help="MCU part number (default: auto-detect)")
+    baseline_parser.add_argument("--ioc", help="path to the .ioc (default: auto-detect)")
+    baseline_parser.add_argument("--schematic-dir", help="directory of .SchDoc sheets")
+    baseline_parser.add_argument("--schematic-component",
+                                 help="MCU designator when a sheet set has several MCU instances")
+    baseline_parser.add_argument("--target", help=f"target name from {config.CONFIG_NAME}")
+    baseline_parser.add_argument("--kicad-project", help="KiCad project (.kicad_pro or its folder)")
+    baseline_parser.add_argument("--output", type=Path, help="default: PATH/.pcba-baseline.json")
+    baseline_parser.add_argument(
+        "--reason",
+        default="Present when the project baseline was created.",
+        help="reason recorded for every generated suppression",
+    )
+    baseline_parser.set_defaults(func=cmd_baseline)
+
+    inspect = sub.add_parser("inspect", help="what is this project made of?")
+    inspect.add_argument("path", nargs="?", default=".", type=Path)
+    inspect.add_argument("--part")
+    inspect.add_argument("--ioc", help="path to the .ioc (default: auto-detect)")
+    inspect.add_argument("--schematic-dir", help="directory of .SchDoc sheets")
+    inspect.add_argument("--schematic-component", help="MCU designator when a sheet set has several MCU instances")
+    inspect.add_argument("--target", help=f"target name from {config.CONFIG_NAME}")
+    inspect.add_argument("--kicad-project", help="KiCad project (.kicad_pro or its folder)")
+    add_format(inspect)
+    inspect.set_defaults(func=cmd_inspect)
+
+    cubemx = sub.add_parser("cubemx", help="read STM32CubeMX .ioc files")
+    cubemx.add_argument("--db", help="CubeMX db/mcu directory")
+    csub = cubemx.add_subparsers(dest="cubemx_command", required=True)
+    for name, help_text in (
+        ("pins", "every assigned pin: signal, label"),
+        ("peripherals", "enabled-peripheral list"),
+        ("clocks", "RCC / clock-tree values"),
+        ("free", "peripherals the part has but the project does not use"),
+    ):
+        child = csub.add_parser(name, help=help_text)
+        child.add_argument("ioc", type=Path)
+        add_format(child)
+    child = csub.add_parser("get", help="raw key lookup (exact or prefix)")
+    child.add_argument("ioc", type=Path)
+    child.add_argument("keys", nargs="+")
+    add_format(child)
+    child = csub.add_parser("af", help="alternate functions a pin can carry")
+    child.add_argument("ioc", type=Path)
+    child.add_argument("pin")
+    add_format(child)
+    child = csub.add_parser("diff", help="what changed between two .ioc files (non-zero if any)")
+    child.add_argument("old", type=Path)
+    child.add_argument("new", type=Path)
+    add_format(child)
+    child = csub.add_parser("validate", help="check the .ioc against a manifest")
+    child.add_argument("ioc", type=Path)
+    child.add_argument("manifest", type=Path)
+    add_format(child)
+
+    # Class C: drives CubeMX's GUI. Disabled until writes go through the change-plan
+    # workflow; the parser stays so existing invocations fail with an explanation.
+    child = csub.add_parser(
+        "drive", help="disabled: unrestricted CubeMX writes wait for the change-plan workflow"
+    )
+    child.add_argument("script", type=Path, help="CubeMX .mx script")
+    child.add_argument("--expect", type=Path, help="file the script must produce")
+    child.add_argument(
+        "--answer", action="append", default=[], metavar="GLOB=BUTTON",
+        help='answer a modal dialog, e.g. "Memory Protection*=No"',
+    )
+    child.add_argument("--timeout", type=int, default=300)
+    child.add_argument("--app", help="path to STM32CubeMX.app")
+
+    child = csub.add_parser(
+        "roundtrip",
+        help="load+save through CubeMX and diff — detects hand-edits (macOS GUI session only)",
+    )
+    child.add_argument("ioc", type=Path)
+    child.add_argument("--timeout", type=int, default=300)
+    child.add_argument("--app", help="path to STM32CubeMX.app")
+    add_format(child)
+
+    cubemx.set_defaults(func=cmd_cubemx)
+
+    altium_parser = sub.add_parser("altium", help="read Altium schematics; drive Altium Designer (Windows)")
+    asub = altium_parser.add_subparsers(dest="altium_command", required=True)
+    child = asub.add_parser("pinmap", help="extract the MCU pin -> net map")
+    child.add_argument("--dir", default=".", help="directory of .SchDoc sheets")
+    child.add_argument("--part", help="MCU part number (default: auto-detect)")
+    child.add_argument("--schematic-component", help="MCU designator when a sheet set has several MCU instances")
+    add_format(child)
+    child = asub.add_parser("netlist", help="every net of a schematic folder (flat, global labels)")
+    child.add_argument("--dir", default=".", help="directory of .SchDoc sheets (binary or ASCII)")
+    add_format(child)
+    child = asub.add_parser(
+        "project-sheets", help="inspect project sheets and structural instances; no electrical netlist"
+    )
+    child.add_argument("--project", required=True, help=".PrjPcb file; only its listed schematic files are read")
+    add_format(child)
+    asub.add_parser("mcp", help="run the Altium drive MCP server on stdio (Windows, Altium running)")
+    asub.add_parser("status", help="report the Altium installation and the bridge state")
+    child = asub.add_parser("house-rules", help="Newmatik house DFM rules as an Altium .RUL file or JSON")
+    child.add_argument("--out", help="write the .RUL file here (default: print it)")
+    child.add_argument("--format", choices=["rul", "json"], default="rul")
+    child = asub.add_parser("call", help="call one Altium drive tool (same as the MCP server) and print its reply")
+    child.add_argument("tool", help="tool name, e.g. altium_status, altium_read, altium_dfm")
+    child.add_argument("--args", help="tool arguments: a JSON object, or @file.json")
+    child.add_argument("--out", help="write the reply to this file instead of printing it")
+    child = asub.add_parser("apply", help="plan typed operations from a file and apply them with --yes")
+    child.add_argument("--ops", required=True, help="the operations: a JSON list, or @ops.json")
+    child.add_argument("--summary", required=True, help="what the change does, for the record")
+    child.add_argument("--project", help="the .PrjPcb (for verification and the change record)")
+    child.add_argument("--sheets-dir", help="schematic folder for the engine's verification")
+    child.add_argument("--expect-nets", help="expected nets: JSON object or @nets.json")
+    child.add_argument("--allow-destructive", action="store_true", help="the plan may remove design content")
+    child.add_argument("--yes", action="store_true", help="apply after planning (you approve the preview)")
+    child.add_argument("--out", help="write the reply to this file")
+    asub.add_parser("remanifest", help="developer: recompute the bridge's MANIFEST.json after editing bridge.pas")
+    altium_parser.set_defaults(func=cmd_altium)
+
+    kicad_parser = sub.add_parser("kicad", help="read KiCad projects: netlist, MCU pin map, board summary")
+    ksub = kicad_parser.add_subparsers(dest="kicad_command", required=True)
+    child = ksub.add_parser("netlist", help="every net of a KiCad schematic hierarchy, built from wire geometry")
+    child.add_argument("project", nargs="?", default=".", help=".kicad_pro, root .kicad_sch, or its folder")
+    add_format(child)
+    child = ksub.add_parser("pinmap", help="extract the MCU pin -> net map from a KiCad schematic")
+    child.add_argument("project", nargs="?", default=".", help=".kicad_pro, root .kicad_sch, or its folder")
+    child.add_argument("--part", help="MCU part number (default: auto-detect)")
+    child.add_argument("--schematic-component", help="MCU reference when the schematic has several MCUs")
+    add_format(child)
+    child = ksub.add_parser("board", help="footprints, nets, tracks and outline of a .kicad_pcb")
+    child.add_argument("project", nargs="?", default=".", help=".kicad_pcb or the project folder")
+    add_format(child)
+    kicad_parser.set_defaults(func=cmd_kicad)
+
+    doctor_parser = sub.add_parser(
+        "doctor", help="check what driving Altium or Fusion, and the KiCad checks, need on this machine")
+    doctor_parser.add_argument("--no-ping", action="store_true", help="do not ping a running Altium")
+    add_format(doctor_parser)
+    doctor_parser.set_defaults(func=cmd_doctor)
+
+    mcp = sub.add_parser("mcp", help="run the MCP server on stdio")
+    mcp.set_defaults(func=cmd_mcp)
+
+    return parser
+
+
+def _utf8_console() -> None:
+    """A Windows console defaults to cp1252, and printing a check mark or a non-Latin net name then
+    failed with UnicodeEncodeError. Write UTF-8, replacing what a terminal cannot show."""
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure") and (stream.encoding or "").lower() not in ("utf-8", "utf8"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):  # a stream that cannot be reconfigured keeps its encoding
+                pass
+
+
+# Class C adapters whose controlled failures the CLI reports like any other bad input.
+_DRIVE_MODULES = ("pcba.adapters.cubemx_drive", "pcba.adapters.altium_drive")
+
+
+def _controlled_errors() -> tuple[type[BaseException], ...]:
+    """Failures reported as `error: ...` with exit 2 rather than as an internal error.
+
+    An adapter's DriveError joins only when a subcommand has already loaded that adapter.
+    Importing it here, for every command, put `pcba.adapters` on the review path that CI
+    runs; `enginehall review` never needs it.
+    """
+    errors: tuple[type[BaseException], ...] = (
+        baseline.BaselineError,
+        changes.ChangeSetError,
+        config.ProjectConfigError,
+        publish.PublishError,
+        IocError,
+        SchDocError,
+        KicadError,
+        SexprError,
+        OSError,
+    )
+    loaded = (sys.modules.get(name) for name in _DRIVE_MODULES)
+    return errors + tuple(module.DriveError for module in loaded if module is not None)
+
+
+def _prog() -> str:
+    """The name the command was started as, for usage lines; `python -m pcba.cli` is `enginehall`."""
+    name = os.path.splitext(os.path.basename(sys.argv[0] if sys.argv else ""))[0].lower()
+    return name if name in COMMANDS else "enginehall"
+
+
+def run(argv: list[str] | None = None, prog: str | None = None) -> int:
+    _utf8_console()
+    args = build_parser(prog or _prog()).parse_args(argv)
+    try:
+        return args.func(args)
+    except BrokenPipeError:  # `enginehall review | head`; an OSError, so it must come first
+        return EXIT_OK
+    except _controlled_errors() as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        return 130
+    except Exception:
+        # Exit 1 means "findings". An internal failure must never read as a normal result.
+        traceback.print_exc()
+        print("error: internal error; please report the traceback above", file=sys.stderr)
+        return EXIT_ERROR
+
+
+def run_deprecated(argv: list[str] | None = None) -> int:
+    """The `pcba` console script: one line on stderr, then the same command. stdout, exit codes and
+    the MCP stdio stream are unchanged, so scripts, CI and MCP hosts keep working."""
+    print(DEPRECATION, file=sys.stderr)
+    return run(argv, prog="pcba")
+
+
+def main() -> None:  # pragma: no cover
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()