wirestudio 0.43.0__tar.gz → 0.45.0__tar.gz

{wirestudio-0.43.0/wirestudio.egg-info → wirestudio-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wirestudio
-Version: 0.43.0
+Version: 0.45.0
 Summary: Agent-driven IoT device design tool that produces ESPHome YAML.
 Author: wirestudio contributors
 License: MIT
@@ -19,6 +19,7 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: slowapi>=0.1.9
 Requires-Dist: mcp<3,>=2.0
 Requires-Dist: websockets>=12
+Requires-Dist: pillow>=10
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"

{wirestudio-0.43.0 → wirestudio-0.45.0}/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
     "slowapi>=0.1.9",
     "mcp>=2.0,<3",
     "websockets>=12",
+    "pillow>=10",
 ]
 
 [project.optional-dependencies]

{wirestudio-0.43.0 → wirestudio-0.45.0}/tests/test_api_route.py

@@ -99,3 +99,9 @@ def test_fab_gerbers_route_unavailable_is_503(client, monkeypatch):
 def test_fab_status_reports_route(client):
     body = client.get("/design/fab/status").json()
     assert "route" in body and "route_reason" in body
+
+
+def test_route_bad_params_are_422(client, toolchain):
+    for query in ("keepout=1,2,3", "keepout=1,2,3,4,pads", "via_costs=-5", "passes=0"):
+        resp = client.post(f"/design/kicad/route?{query}", json=_design())
+        assert resp.status_code == 422, query

wirestudio-0.45.0/tests/test_community.py

@@ -0,0 +1,248 @@
+"""Community designs: browse and import go through the catalogue's index
+only, and share refuses what the catalogue's CI would."""
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+from pathlib import Path
+
+import pytest
+import yaml
+from fastapi.testclient import TestClient
+
+from wirestudio.api.app import create_app
+
+REPO = "moellere/wirestudio-designs"
+RAW = f"https://raw.githubusercontent.com/{REPO}"
+EXAMPLE = json.loads((Path(__file__).resolve().parent.parent / "wirestudio" / "examples"
+                      / "garage-motion.json").read_text())
+
+
+def _entry(slug, **over):
+    return {"slug": slug, "name": "Porch motion", "author": "octocat", "license": "CC-BY-4.0",
+            "design_url": f"{RAW}/main/designs/{slug}/design.json", **over}
+
+
+@pytest.fixture
+def user_library(tmp_path):
+    from wirestudio.library import Library, default_library
+
+    return Library(default_library().root, tmp_path / "user-library")
+
+
+@pytest.fixture
+def studio(monkeypatch, user_library):
+    monkeypatch.delenv("WIRESTUDIO_DESIGNS_REPO", raising=False)
+    files: dict[str, bytes] = {}
+    fetched: list[str] = []
+
+    async def fetch(url):
+        fetched.append(url)
+        if url not in files:
+            raise RuntimeError(f"404 {url}")
+        return files[url]
+
+    def publish(*entries, designs=None, components=None):
+        files[f"{RAW}/index/index.json"] = json.dumps(
+            {"version": 1, "generated": "2026-10-23T00:00:00+00:00", "designs": list(entries)}).encode()
+        for slug, doc in (designs or {}).items():
+            files[f"{RAW}/main/designs/{slug}/design.json"] = json.dumps(doc).encode()
+        for url, text in (components or {}).items():
+            files[url] = text.encode()
+
+    app = TestClient(create_app(library=user_library, community_fetch=fetch))
+    return app, publish, fetched
+
+
+def test_status_names_the_catalogue(studio):
+    app, _, _ = studio
+    s = app.get("/community/status").json()
+    assert s["enabled"] and s["repo"] == REPO
+    assert s["upload_url"] == f"https://github.com/{REPO}/upload/main/designs"
+
+
+def test_empty_repo_setting_turns_it_off(studio, monkeypatch):
+    app, _, _ = studio
+    monkeypatch.setenv("WIRESTUDIO_DESIGNS_REPO", "")
+    assert app.get("/community/status").json() == {"enabled": False}
+    assert app.get("/community/designs").status_code == 503
+
+
+def test_browse_lists_the_index_and_caches_it(studio):
+    app, publish, fetched = studio
+    publish(_entry("porch-motion"))
+    assert [d["slug"] for d in app.get("/community/designs").json()["designs"]] == ["porch-motion"]
+    app.get("/community/designs")
+    assert fetched.count(f"{RAW}/index/index.json") == 1
+
+
+def test_an_unreachable_index_is_a_502(studio):
+    app, _, _ = studio
+    r = app.get("/community/designs")
+    assert r.status_code == 502 and "index unavailable" in r.json()["detail"]
+
+
+def test_import_stamps_the_origin(studio):
+    app, publish, _ = studio
+    publish(_entry("porch-motion"), designs={"porch-motion": {**EXAMPLE, "id": "porch-motion"}})
+    body = app.post("/community/designs/porch-motion/import").json()
+    assert body["design"]["origin"] == {"catalogue": REPO, "slug": "porch-motion",
+                                        "author": "octocat", "license": "CC-BY-4.0"}
+    assert app.post("/design/validate", json=body["design"]).status_code == 200
+
+
+def test_import_only_follows_urls_inside_the_catalogue(studio):
+    app, publish, fetched = studio
+    publish(_entry("evil", design_url="http://169.254.169.254/latest/meta-data"))
+    assert app.post("/community/designs/evil/import").status_code == 502
+    assert not any("169.254" in u for u in fetched)
+
+
+def test_import_of_an_unknown_slug_is_a_404(studio):
+    app, publish, _ = studio
+    publish()
+    assert app.post("/community/designs/nope/import").status_code == 404
+
+
+def _share(app, **over):
+    body = {"design": {**EXAMPLE, "id": "Porch Motion v2"}, "author": "@octocat", "tags": ["motion"], **over}
+    return app.post("/community/share", json=body)
+
+
+def test_share_packs_the_folder_the_catalogue_expects(studio):
+    app, _, _ = studio
+    r = _share(app, notes="Built on a DevKitC.")
+    assert r.status_code == 200 and r.headers["content-type"] == "application/zip"
+    z = zipfile.ZipFile(io.BytesIO(r.content))
+    assert sorted(z.namelist()) == ["porch-motion-v2/README.md", "porch-motion-v2/design.json",
+                                    "porch-motion-v2/meta.yaml"]
+    assert json.loads(z.read("porch-motion-v2/design.json"))["id"] == "porch-motion-v2"
+    assert yaml.safe_load(z.read("porch-motion-v2/meta.yaml")) == {"author": "octocat", "tags": ["motion"]}
+
+
+def test_share_credits_the_design_it_was_imported_from(studio):
+    app, _, _ = studio
+    origin = {"catalogue": REPO, "slug": "porch-motion", "author": "someone", "license": "CC-BY-4.0"}
+    r = _share(app, design={**EXAMPLE, "id": "porch-motion-v2", "origin": origin})
+    z = zipfile.ZipFile(io.BytesIO(r.content))
+    assert yaml.safe_load(z.read("porch-motion-v2/meta.yaml"))["derived_from"] == "porch-motion"
+    assert "origin" not in json.loads(z.read("porch-motion-v2/design.json"))
+
+
+def test_resharing_your_own_design_does_not_derive_from_itself(studio):
+    app, _, _ = studio
+    origin = {"catalogue": REPO, "slug": "porch-motion", "author": "octocat", "license": "CC-BY-4.0"}
+    r = _share(app, design={**EXAMPLE, "id": "porch-motion", "origin": origin})
+    z = zipfile.ZipFile(io.BytesIO(r.content))
+    assert "derived_from" not in yaml.safe_load(z.read("porch-motion/meta.yaml"))
+
+
+def test_share_refuses_a_literal_credential(studio):
+    app, _, _ = studio
+    design = json.loads(json.dumps(EXAMPLE))
+    design["fleet"]["secrets_ref"]["wifi_password"] = "hunter22"
+    r = _share(app, design=design)
+    assert r.status_code == 422 and "fleet.secrets_ref.wifi_password" in r.json()["detail"]
+
+
+@pytest.mark.parametrize("over, match", [
+    ({"author": "not a handle"}, "GitHub handle"),
+    ({"tags": ["Has Space"]}, "tags"),
+    ({"slug": "Bad_Slug"}, "not a usable name"),
+])
+def test_share_refuses_what_the_catalogue_would(studio, over, match):
+    app, _, _ = studio
+    r = _share(app, **over)
+    assert r.status_code == 422 and match in r.json()["detail"]
+
+
+def _jpeg(size=(3000, 2000), exif=True, fmt="JPEG") -> str:
+    import base64
+
+    from PIL import Image
+
+    img = Image.new("RGB", size, (200, 80, 40))
+    kwargs = {}
+    if exif:
+        e = Image.Exif()
+        e[0x010F] = "PhoneMaker"
+        e[0x0112] = 6  # Orientation: rotate 90 CW on display
+        kwargs["exif"] = e
+    buf = io.BytesIO()
+    img.save(buf, fmt, **kwargs)
+    return base64.b64encode(buf.getvalue()).decode()
+
+
+def test_share_re_encodes_photos_without_metadata(studio):
+    from PIL import Image
+
+    app, _, _ = studio
+    r = _share(app, photos=[{"name": "IMG_0042.JPG", "data": _jpeg()},
+                            {"name": "IMG_0042.JPG", "data": _jpeg(fmt="PNG", exif=False)}])
+    assert r.status_code == 200, r.text
+    z = zipfile.ZipFile(io.BytesIO(r.content))
+    names = sorted(n for n in z.namelist() if "/photos/" in n)
+    assert names == ["porch-motion-v2/photos/img-0042-2.jpg", "porch-motion-v2/photos/img-0042.jpg"]
+    with Image.open(io.BytesIO(z.read("porch-motion-v2/photos/img-0042.jpg"))) as img:
+        assert img.format == "JPEG" and not img.getexif()
+        assert img.size == (1365, 2048), "the EXIF rotation is applied before EXIF is dropped"
+    assert all(z.getinfo(n).file_size <= 1024 * 1024 for n in names)
+
+
+def test_share_refuses_what_is_not_a_photo(studio):
+    import base64
+
+    app, _, _ = studio
+    r = _share(app, photos=[{"name": "notes.txt", "data": base64.b64encode(b"hello").decode()}])
+    assert r.status_code == 422 and "not a readable image" in r.json()["detail"]
+    r = _share(app, photos=[{"name": f"p{i}.jpg", "data": _jpeg((10, 10))} for i in range(5)])
+    assert r.status_code == 422 and "at most 4" in r.json()["detail"]
+
+
+LED_DRIVER = (Path(__file__).resolve().parent / "fixtures" / "components" / "led_driver_npn.yaml").read_text()
+LED_URL = f"{RAW}/main/designs/porch-led/components/led_driver_npn.yaml"
+
+
+def _led_design() -> dict:
+    doc = {**EXAMPLE, "id": "porch-led"}
+    doc["components"] = [*EXAMPLE["components"],
+                         {"id": "status", "library_id": "led_driver_npn", "label": "Status LED", "params": {}}]
+    return doc
+
+
+def _publish_led(publish):
+    publish(_entry("porch-led", user_components=[{"id": "led_driver_npn", "url": LED_URL}]),
+            designs={"porch-led": _led_design()}, components={LED_URL: LED_DRIVER})
+
+
+def test_import_installs_the_designs_user_components(studio, user_library):
+    app, publish, _ = studio
+    _publish_led(publish)
+    r = app.post("/community/designs/porch-led/import")
+    assert r.status_code == 200, r.text
+    assert r.json()["installed_components"] == ["led_driver_npn"]
+    assert user_library.component_source("led_driver_npn") == "user"
+    again = app.post("/community/designs/porch-led/import").json()
+    assert again["installed_components"] == [], "the same text is already here"
+
+
+def test_import_never_overwrites_a_different_user_component(studio, user_library):
+    app, publish, _ = studio
+    _publish_led(publish)
+    user_library.save_component("led_driver_npn", LED_DRIVER.replace("NPN low-side LED driver", "mine", 1))
+    r = app.post("/community/designs/porch-led/import")
+    assert r.status_code == 409 and "different component 'led_driver_npn'" in r.json()["detail"]
+    assert "mine" in user_library.component_yaml("led_driver_npn")
+
+
+def test_share_packs_the_user_components_the_design_uses(studio, user_library):
+    app, _, _ = studio
+    user_library.save_component("led_driver_npn", LED_DRIVER)
+    r = _share(app, design=_led_design())
+    assert r.status_code == 200, r.text
+    z = zipfile.ZipFile(io.BytesIO(r.content))
+    slug = "porch-led"
+    assert z.read(f"{slug}/components/led_driver_npn.yaml").decode() == LED_DRIVER
+    assert not [n for n in z.namelist() if "/components/" in n and "led_driver_npn" not in n], \
+        "bundled components are not packed"

{wirestudio-0.43.0 → wirestudio-0.45.0}/tests/test_compatibility.py

@@ -58,31 +58,41 @@ def test_no_board_silently_returns_empty(lib):
     assert check_pin_compatibility({"components": [], "connections": []}, lib) == []
 
 
-def test_input_only_as_output_is_an_error(lib):
-    """
-    GPIO34 on ESP32-DevKitC-V4 is input-only. Wiring an output role to it
-    should emit a hard error.
-    """
-    d = _load("garage-motion")
-    # Reroute pir1.OUT (digital_out) to GPIO34 (input-only).
+def _with_lamp(d: dict, pin: str) -> dict:
+    """garage-motion plus a relay/LED output the MCU drives, on `pin`."""
+    d["components"].append({"id": "lamp", "library_id": "gpio_output", "label": "Lamp", "params": {}})
+    d["connections"].append({"component_id": "lamp", "pin_role": "OUT",
+                             "target": {"kind": "gpio", "pin": pin}})
+    return d
+
+
+def _move_pir(d: dict, pin: str) -> dict:
     for c in d["connections"]:
         if c["component_id"] == "pir1" and c["pin_role"] == "OUT":
-            c["target"] = {"kind": "gpio", "pin": "GPIO34"}
-    warnings = check_pin_compatibility(d, lib)
+            c["target"] = {"kind": "gpio", "pin": pin}
+    return d
+
+
+def test_input_only_as_output_is_an_error(lib):
+    """GPIO34 on ESP32-DevKitC-V4 is input-only; an output the MCU drives
+    there is a hard error."""
+    warnings = check_pin_compatibility(_with_lamp(_load("garage-motion"), "GPIO34"), lib)
     errs = _by_code(warnings, "input_only_as_output")
     assert len(errs) == 1
     assert errs[0].severity == "error"
     assert errs[0].pin == "GPIO34"
 
 
+def test_a_sensor_output_on_an_input_only_pin_is_fine(lib):
+    """A PIR's OUT is the MCU's input: GPIO34-39 are the usual place for it."""
+    warnings = check_pin_compatibility(_move_pir(_load("garage-motion"), "GPIO34"), lib)
+    assert warnings == []
+
+
 def test_boot_high_pin_used_as_output_warns(lib):
     """ESP32 GPIO0 is boot_high (must be HIGH at boot). Driving it as a digital
     output should warn."""
-    d = _load("garage-motion")
-    for c in d["connections"]:
-        if c["component_id"] == "pir1" and c["pin_role"] == "OUT":
-            c["target"] = {"kind": "gpio", "pin": "GPIO0"}
-    warnings = check_pin_compatibility(d, lib)
+    warnings = check_pin_compatibility(_with_lamp(_load("garage-motion"), "GPIO0"), lib)
     boot = _by_code(warnings, "boot_strap_output")
     assert len(boot) == 1
     assert boot[0].severity == "warn"
@@ -92,16 +102,23 @@ def test_boot_high_pin_used_as_output_warns(lib):
 def test_boot_low_pin_used_as_output_warns(lib):
     """ESP32 GPIO12 is boot_low (must be LOW at boot, controls flash voltage).
     Output use should warn."""
-    d = _load("garage-motion")
-    for c in d["connections"]:
-        if c["component_id"] == "pir1" and c["pin_role"] == "OUT":
-            c["target"] = {"kind": "gpio", "pin": "GPIO12"}
-    warnings = check_pin_compatibility(d, lib)
+    warnings = check_pin_compatibility(_with_lamp(_load("garage-motion"), "GPIO12"), lib)
     boot = _by_code(warnings, "boot_strap_output")
     assert len(boot) == 1
     assert "LOW at boot" in boot[0].message
 
 
+@pytest.mark.parametrize("pin, level", [("GPIO0", "HIGH"), ("GPIO12", "LOW")])
+def test_a_strap_pin_driven_by_a_sensor_warns(lib, pin, level):
+    """A PIR holds its output at power-up, so on a strap pin it decides the
+    boot mode -- the hazard is the sensor's, even though the MCU reads it."""
+    warnings = check_pin_compatibility(_move_pir(_load("garage-motion"), pin), lib)
+    driven = _by_code(warnings, "boot_strap_driven")
+    assert len(driven) == 1 and driven[0].severity == "warn"
+    assert f"must be {level} at boot" in driven[0].message
+    assert _by_code(warnings, "boot_strap_output") == []
+
+
 def test_boot_strap_pin_as_input_does_not_warn(lib):
     """Buttons wired to boot strap pins (e.g., Sonoff GPIO0 button) are read
     as inputs; the validator should not flag this even though the pin is a
@@ -362,3 +379,50 @@ def test_a_reserved_bus_id_is_an_error(lib):
     assert w.severity == "error"
     assert w.component_id == "uart0"
     assert "uart_bus0" in w.message
+
+
+PART_DRIVEN = {
+    "hc-sr501": ["OUT"], "rcwl-0516": ["OUT"], "ld2410": ["OUT"], "remote_receiver": ["OUT"],
+    "hlw8012": ["CF", "CF1"], "sx127x": ["DIO0"], "wiegand": ["D0", "D1"],
+}
+
+
+@pytest.mark.parametrize("library_id, roles", sorted(PART_DRIVEN.items()))
+def test_part_driven_signals_are_mcu_inputs(lib, library_id, roles):
+    """The audit's verdicts: these lines are outputs of the part, so inputs
+    of the MCU, and the part drives them."""
+    pins = {p.role: p for p in lib.component(library_id).electrical.pins}
+    for role in roles:
+        assert pins[role].kind == "digital_in" and pins[role].driven, f"{library_id}.{role}"
+
+
+def test_the_component_gate_refuses_driven_on_an_output(lib):
+    from wirestudio.library.check import check_component_yaml
+
+    text = (REPO_ROOT / "tests" / "fixtures" / "components" / "led_driver_npn.yaml").read_text()
+    assert check_component_yaml(text, lib).ok
+    bad = text.replace("kind: digital_out", "kind: digital_out, driven: true", 1)
+    assert bad != text
+    report = check_component_yaml(bad, lib)
+    assert not report.ok and any("`driven`" in e for e in report.errors)
+
+
+def _with_receivers(d: dict, n: int, **params) -> dict:
+    for i, pin in enumerate(("GPIO32", "GPIO33", "GPIO25", "GPIO26")[:n]):
+        d["components"].append({"id": f"rx{i}", "library_id": "remote_receiver",
+                                "label": f"RX {i}", "params": dict(params)})
+        d["connections"].append({"component_id": f"rx{i}", "pin_role": "OUT",
+                                 "target": {"kind": "gpio", "pin": pin}})
+    return d
+
+
+def test_a_third_remote_receiver_on_a_classic_esp32_warns(lib):
+    assert _by_code(check_pin_compatibility(_with_receivers(_load("garage-motion"), 2), lib), "rmt_memory") == []
+    warns = _by_code(check_pin_compatibility(_with_receivers(_load("garage-motion"), 3), lib), "rmt_memory")
+    assert len(warns) == 1 and warns[0].component_id == "rx2"
+    assert "rmt_symbols" in warns[0].message
+
+
+def test_receivers_with_rmt_symbols_set_do_not_warn(lib):
+    d = _with_receivers(_load("garage-motion"), 3, rmt_symbols=128)
+    assert _by_code(check_pin_compatibility(d, lib), "rmt_memory") == []

{wirestudio-0.43.0 → wirestudio-0.45.0}/tests/test_kicad.py

@@ -14,12 +14,14 @@ The generator is pure text-out, so we lean on substring assertions +
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 
 import pytest
 
 from wirestudio.kicad import generate_skidl
 from wirestudio.kicad.generator import _py_var
+from wirestudio.kicad.netlist import build_netlist
 from wirestudio.library import default_library
 from wirestudio.model import Design
 
@@ -160,15 +162,24 @@ def test_rail_targets_become_named_nets(lib):
     assert 'NET_PLUS__3V3 = Net("+3V3")' in script
 
 
-def test_bus_targets_share_a_single_net(lib):
-    """All connections targeting bus_id=i2c0 should resolve to the same
-    NET_BUS_i2c0 handle so the schematic's I2C pins land on one net."""
+def test_bus_targets_land_on_a_net_per_line(lib):
+    """A bus is a net per line: the BME280's SDA and SCL go to i2c0's SDA
+    and SCL nets, never one shared net. The symbol's I2C pins are SDI/SCK
+    (pin_map rewrites SDA->SDI, SCL->SCK)."""
     script = generate_skidl(_design("garage-motion"), lib)
-    assert 'NET_BUS_i2c0 = Net("BUS_i2c0")' in script
-    # Both BME280's I2C connections go to that single bus net. The
-    # symbol's I2C pins are SDI/SCK (pin_map rewrites SDA->SDI, SCL->SCK).
-    assert 'c_bme1["SDI"] += NET_BUS_i2c0' in script
-    assert 'c_bme1["SCK"] += NET_BUS_i2c0' in script
+    assert 'NET_BUS_i2c0_SDA = Net("BUS_i2c0_SDA")' in script
+    assert 'NET_BUS_i2c0_SCL = Net("BUS_i2c0_SCL")' in script
+    assert 'Net("BUS_i2c0")' not in script
+    assert 'c_bme1["SDI"] += NET_BUS_i2c0_SDA' in script
+    assert 'c_bme1["SCK"] += NET_BUS_i2c0_SCL' in script
+
+
+def test_uart_lines_cross_over(lib):
+    """A UART part's TX is the MCU's RX line, and its RX the MCU's TX."""
+    nets = {n.name: {(p.ref, p.pin_role) for p in n.pads}
+            for n in build_netlist(_design("nextion-thermostat"), lib)}
+    assert nets["BUS_nextion_uart_RX"] == {("U1", "TX"), ("M1", "IO16")}
+    assert nets["BUS_nextion_uart_TX"] == {("U1", "RX"), ("M1", "IO17")}
 
 
 def test_gpio_targets_share_one_declared_net(lib):
@@ -187,8 +198,8 @@ def test_board_pins_join_gpio_rail_and_bus_nets(lib):
     the module's VDD, and 5V has no module pin, which the script says."""
     script = generate_skidl(_design("garage-motion"), lib)
     assert 'board["IO13"] += NET_GPIO_GPIO13  # GPIO13' in script
-    assert 'board["IO21"] += NET_BUS_i2c0  # GPIO21' in script
-    assert 'board["IO22"] += NET_BUS_i2c0  # GPIO22' in script
+    assert 'board["IO21"] += NET_BUS_i2c0_SDA  # GPIO21' in script
+    assert 'board["IO22"] += NET_BUS_i2c0_SCL  # GPIO22' in script
     assert 'board["VDD"] += NET_PLUS__3V3  # 3V3' in script
     assert 'board["GND"] += GND  # GND' in script
     assert "# 5V: no pin on RF_Module:ESP32-WROOM-32" in script
@@ -198,8 +209,8 @@ def test_board_pins_use_the_boards_own_role_names(lib):
     """A D1 mini design names pins D1/D2; the pin_map turns them into the
     symbol's SCL/D1 and SDA/D2."""
     script = generate_skidl(_design("room-climate"), lib)
-    assert 'board["SDA/D2"] += NET_BUS_' in script
-    assert 'board["SCL/D1"] += NET_BUS_' in script
+    assert re.search(r'board\["SDA/D2"\] \+= NET_BUS_\w+_SDA ', script)
+    assert re.search(r'board\["SCL/D1"\] \+= NET_BUS_\w+_SCL ', script)
     assert 'board["3V3"] += NET_PLUS__3V3' in script
 
 

wirestudio-0.45.0/tests/test_kicad_drc.py

@@ -0,0 +1,112 @@
+"""Routed DRC: kicad-cli's report summarised for people, stored with the
+routed board, and served by the API and route_pcb.
+
+kicad-cli itself runs in CI's pcb-route gate, which also checks this path
+reports the airwires of an unrouted board; here its JSON comes from a
+fixture captured from KiCad 8 on the unrouted garage-motion board."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from wirestudio.kicad import drc as drc_mod
+from wirestudio.kicad.drc import WAIVED, summarize
+from wirestudio.kicad.route import routed_drc
+
+FIXTURE = json.loads((Path(__file__).parent / "fixtures" / "drc_unrouted_garage_motion.json").read_text())
+
+
+def test_summary_leads_with_the_airwires():
+    s = summarize(FIXTURE)
+    assert s["unconnected"] == 7 and s["ok"] is False
+    assert s["groups"][0]["type"] == "unconnected_items"
+    first = s["groups"][0]["violations"][0]["items"][0]
+    assert first["description"].startswith("Pad ") and first["pos"]["x"] is not None
+
+
+def test_footprint_inherent_types_are_waived_not_failed():
+    s = summarize(FIXTURE)
+    drill = next(g for g in s["groups"] if g["type"] == "drill_out_of_range")
+    assert drill["waived"] and drill["count"] == 12 and drill["reason"] == WAIVED["drill_out_of_range"]
+    assert s["errors"] == 0, "the only errors besides airwires are waived"
+    assert [g["waived"] for g in s["groups"]][-1] is True, "waived groups sort last"
+
+
+def test_a_routed_board_with_a_short_is_not_ok():
+    report = {"violations": [{"type": "shorting_items", "severity": "error",
+                              "description": "Items shorting two nets", "items": []}],
+              "unconnected_items": []}
+    s = summarize(report)
+    assert s["ok"] is False and s["errors"] == 1 and s["unconnected"] == 0
+
+
+def test_a_clean_routed_board_is_ok():
+    report = {"violations": [{"type": "silk_overlap", "severity": "warning", "description": "x", "items": []}],
+              "unconnected_items": []}
+    s = summarize(report)
+    assert s["ok"] is True and s["warnings"] == 0 and s["waived"] == 1
+
+
+@pytest.fixture
+def slot(tmp_path):
+    key = "0123456789abcdef"
+    (tmp_path / key).mkdir()
+    (tmp_path / key / "routed.kicad_pcb").write_text("(kicad_pcb (segment (net 1)))")
+    return tmp_path, key
+
+
+def test_routed_drc_runs_once_and_is_stored(slot, monkeypatch):
+    cache, key = slot
+    calls = []
+    monkeypatch.setattr(drc_mod, "drc_status", lambda: {"available": True, "reason": None})
+    monkeypatch.setattr(drc_mod, "run_drc", lambda text: calls.append(text) or summarize(FIXTURE))
+    first = routed_drc(key, cache_dir=cache)
+    second = routed_drc(key, cache_dir=cache)
+    assert first == second and first["unconnected"] == 7
+    assert len(calls) == 1 and (cache / key / "drc.json").is_file()
+
+
+def test_routed_drc_without_kicad_cli_is_none(slot, monkeypatch):
+    cache, key = slot
+    monkeypatch.setattr(drc_mod, "drc_status", lambda: {"available": False, "reason": "no"})
+    assert routed_drc(key, cache_dir=cache) is None
+    assert routed_drc("ffffffffffffffff", cache_dir=cache) is None
+
+
+def test_the_api_serves_the_routed_drc(slot, monkeypatch):
+    from fastapi.testclient import TestClient
+
+    from wirestudio.api.app import create_app
+
+    cache, key = slot
+    monkeypatch.setenv("WIRESTUDIO_ROUTE_CACHE", str(cache))
+    monkeypatch.setattr(drc_mod, "drc_status", lambda: {"available": True, "reason": None})
+    monkeypatch.setattr(drc_mod, "run_drc", lambda text: summarize(FIXTURE))
+    app = TestClient(create_app())
+    body = app.get(f"/design/kicad/route/{key}/drc").json()
+    assert body["unconnected"] == 7 and body["groups"][0]["type"] == "unconnected_items"
+    assert app.get("/design/kicad/route/ffffffffffffffff/drc").status_code == 404
+    assert app.get("/design/kicad/route/nope/drc").status_code == 422
+
+
+def test_route_pcb_brief_drops_item_detail():
+    from wirestudio.agent.tools import _drc_brief
+
+    brief = _drc_brief(summarize(FIXTURE))
+    unconnected = brief["groups"][0]
+    assert unconnected == {"type": "unconnected_items", "severity": "error", "count": 7, "waived": False,
+                           "examples": ["Missing connection between items"] * 3}
+    assert "examples" not in brief["groups"][-1], "waived groups carry counts only"
+
+
+def test_route_pcb_refuses_bad_parameters():
+    from wirestudio.agent.tools import _run_route_pcb
+    from wirestudio.library import default_library
+
+    design = json.loads((Path(__file__).resolve().parent.parent / "wirestudio/examples/garage-motion.json").read_text())
+    out = _run_route_pcb(design, default_library(), keepouts=[{"x": 0, "y": 0, "w": 0, "h": 1}])
+    assert out["ok"] is False and "bad route parameters" in out["error"]
+    out = _run_route_pcb(design, default_library(), via_costs=-1)
+    assert out["ok"] is False and "bad route parameters" in out["error"]