ecadlib 0.3.0__py3-none-any.whl

ecadlib/parts_export.py

@@ -0,0 +1,154 @@
+"""Parts table export for PLM / ERP imports:  ecadlib export-parts plan.json --format csv|json|xlsx -o parts.csv
+
+One row per library part in a librarian plan, with stable columns (COLUMNS; their names and order only ever grow at
+the end, so an import mapping set up once keeps working). Parameters that have no column of their own go in
+"Other Parameters" (CSV / XLSX: "name=value; ..." sorted by name; JSON: an object). Held parts are left out unless
+--include-held. Cells that a spreadsheet would run as a formula get a leading apostrophe in CSV / XLSX (sheetsafe);
+JSON keeps the plain text.
+
+KiCad names ("KiCad Symbol", "KiCad Footprint") are the lib ids `ecadlib kicad-export --name LIB` writes
+(LIB:<part>, LIB:<footprint>), the same ones `ecadlib kicad-dblib` puts in its database."""
+import argparse, json, sys
+from pathlib import Path
+
+from . import sheetsafe as SS
+
+FORMAT_VERSION = 1
+COLUMNS = ["Part ID", "Status", "Category", "Folder", "Description", "Value", "Manufacturer", "Manufacturer Part Number",
+           "Datasheet", "Supplier 1", "Supplier Part Number 1", "Supplier 2", "Supplier Part Number 2",
+           "Lifecycle", "Symbol Ref", "Symbol File", "Footprint Ref", "Footprint File", "KiCad Symbol", "KiCad Footprint",
+           "3D Height (mm)", "Release Check", "Hold Reasons", "Sign-off", "Approved By", "Symbol Source", "Footprint Source",
+           "Other Parameters"]
+PARAM_COLUMNS = {"Value": "Value", "Manufacturer": "Manufacturer", "Manufacturer Part Number": "Manufacturer Part Number",
+                 "ComponentLink2URL": "Datasheet", "Datasheet": "Datasheet", "Supplier 1": "Supplier 1",
+                 "Supplier Part Number 1": "Supplier Part Number 1", "Supplier 2": "Supplier 2",
+                 "Supplier Part Number 2": "Supplier Part Number 2", "Lifecycle": "Lifecycle", "Lifecycle Status": "Lifecycle"}
+SKIP_PARAMS = {"ComponentLink2Description"}
+LIBRARY_STATUS = ("ready", "existing")
+
+
+def kicad_ids(item, lib):
+    from .kicad_export import kname
+    fp = (item.get("footprint") or {})
+    has_fp = fp.get("ref") and (fp.get("file") or fp.get("kicad_mod"))
+    has_sym = (item.get("source") or {}).get("symbol") or (item.get("symbol") or {}).get("file")
+    return (f"{lib}:{kname(item['name'])}" if has_sym else "", f"{lib}:{kname(fp['ref'])}" if has_fp else "")
+
+
+def _signoff(items, base):
+    """{part: (sign-off, approved by)} from the approvals policy next to the plan; {} when there is none."""
+    from . import approvals as A
+    try:
+        policy = A.load_policy(base)
+    except Exception as e:                       # a broken policy file must not stop an export
+        print(f"  warning: approvals policy not read: {e}", file=sys.stderr)
+        return {}
+    if not policy:
+        return {}
+    out = {}
+    for it in items:
+        try:
+            ev = A.evaluate(it, policy, base)
+        except Exception as e:
+            out[it["name"]] = (f"unknown ({type(e).__name__})", "")
+            continue
+        state = "not required" if not ev["required"] else "approved" if not ev["missing"] and not ev["stale"] else "pending"
+        out[it["name"]] = (state, "; ".join(ev["approved_by"]))
+    return out
+
+
+def rows(plan, lib="ecadlib", include_held=False):
+    """Plan items -> [row dict with exactly COLUMNS], sorted by Part ID. plan: path to plan.json or a list of items."""
+    base = Path(plan).parent if not isinstance(plan, list) else Path(".")
+    items = json.loads(Path(plan).read_text(encoding="utf-8")) if not isinstance(plan, list) else plan
+    if not isinstance(items, list):
+        raise ValueError(f"{plan}: not a librarian plan (expected a list of parts)")
+    keep = [it for it in items if isinstance(it, dict) and it.get("name")
+            and (it.get("status", "ready") in LIBRARY_STATUS or (include_held and it.get("status") == "held"))]
+    sign = _signoff(keep, base) if not isinstance(plan, list) else {}
+    out = []
+    for it in sorted(keep, key=lambda i: str(i["name"])):
+        par = {str(p.get("name")): str(p.get("value", "")) for p in it.get("parameters", []) if str(p.get("value", "")).strip()}
+        r = dict.fromkeys(COLUMNS, "")
+        folder = str(it.get("folder") or "")
+        sym, fp = it.get("symbol") or {}, it.get("footprint") or {}
+        ks, kf = kicad_ids(it, lib)
+        rc = it.get("release_check") or {}
+        r.update({"Part ID": str(it["name"]), "Status": str(it.get("status", "ready")),
+                  "Category": folder.rstrip("/").split("/")[-1] if folder else "", "Folder": folder,
+                  "Description": str(it.get("description") or ""), "Symbol Ref": str(sym.get("ref") or ""),
+                  "Symbol File": str(sym.get("file") or ""), "Footprint Ref": str(fp.get("ref") or ""),
+                  "Footprint File": str(fp.get("file") or ""), "KiCad Symbol": ks, "KiCad Footprint": kf,
+                  "3D Height (mm)": f"{float(rc['height']):.2f}" if isinstance(rc.get("height"), (int, float)) else "",
+                  "Release Check": str(rc.get("result") or ""), "Hold Reasons": "; ".join(it.get("hold_reasons") or []),
+                  "Symbol Source": str((it.get("source") or {}).get("symbol") or ""),
+                  "Footprint Source": str((it.get("source") or {}).get("footprint") or "")})
+        r["Sign-off"], r["Approved By"] = sign.get(it["name"], ("", ""))
+        other = {}
+        for k in sorted(par):
+            col = PARAM_COLUMNS.get(k)
+            if col and not r[col]:
+                r[col] = par[k]
+            elif k not in SKIP_PARAMS and not col:
+                other[k] = par[k]
+        r["Other Parameters"] = other
+        out.append(r)
+    return out
+
+
+def _flat(r):
+    return {k: ("; ".join(f"{a}={b}" for a, b in v.items()) if isinstance(v, dict) else v) for k, v in r.items()}
+
+
+def write(rs, out, fmt):
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if fmt == "json":
+        out.write_text(json.dumps({"format": "ecadlib-parts", "version": FORMAT_VERSION, "columns": COLUMNS, "parts": rs},
+                                  indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    elif fmt == "csv":
+        with open(out, "w", newline="", encoding="utf-8-sig") as f:      # utf-8-sig: Excel opens it as UTF-8
+            w = SS.DictWriter(f, fieldnames=COLUMNS)
+            w.writeheader()
+            w.writerows(_flat(r) for r in rs)
+    elif fmt == "xlsx":
+        from openpyxl import Workbook
+        from openpyxl.cell.cell import ILLEGAL_CHARACTERS_RE      # control characters (a \x0b from a datasheet) that
+        wb = Workbook()                                            # XML can't hold: openpyxl refuses the whole file
+        ws = wb.active
+        ws.title = "Parts"
+        ws.append(COLUMNS)
+        for r in rs:
+            ws.append([SS.cell(ILLEGAL_CHARACTERS_RE.sub(" ", str(_flat(r)[c]))) for c in COLUMNS])
+        for row in ws.iter_rows(min_row=2):
+            for c in row:
+                c.data_type, c.number_format = "s", "@"                    # text: '0603' and '1e-7' stay as typed
+        ws.freeze_panes = "A2"
+        wb.save(out)
+    else:
+        raise ValueError(f"unknown format {fmt!r}: csv, json or xlsx")
+    return out
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Export the library's parts table (stable columns) for PLM / ERP imports")
+    ap.add_argument("plan", help="librarian plan.json")
+    ap.add_argument("--format", choices=("csv", "json", "xlsx"), help="default: from the -o suffix, else csv")
+    ap.add_argument("-o", "--out", help="output file (default: parts.<format> next to the plan)")
+    ap.add_argument("--name", default="ecadlib", help="KiCad library name used by kicad-export (default %(default)s)")
+    ap.add_argument("--include-held", action="store_true", help="also export parts the release check held")
+    a = ap.parse_args(argv)
+    fmt = a.format or (Path(a.out).suffix.lower().lstrip(".") if a.out and Path(a.out).suffix.lower() in (".csv", ".json", ".xlsx") else "csv")
+    out = Path(a.out) if a.out else Path(a.plan).parent / f"parts.{fmt}"
+    try:
+        rs = rows(a.plan, a.name, a.include_held)
+    except (OSError, ValueError) as e:
+        print(f"cannot read plan: {e}", file=sys.stderr)
+        return 2
+    write(rs, out, fmt)
+    print(f"wrote {len(rs)} parts to {out} ({fmt})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ecadlib/partview.py

@@ -0,0 +1,215 @@
+"""The library plan of one BOM as people see it: one card per part with its status in plain words (ready, held,
+waiting for sign-off), each held reason as a sentence plus a next step, the cross-check and KiCad/Altium results with
+both values when they disagree, the datasheet link (and page when known), what reading the datasheet cost and which
+model read it, and a small footprint picture. Read-only; used by the web UI (Workspace.library_parts).
+
+Held-reason wording comes from ecadlib.messages (the shared voice, docs/ui-voice.md)."""
+import json, re
+from pathlib import Path
+
+from . import messages as M
+
+FIELD = {"pin_count": "pin count", "pitch": "pin pitch", "body_length": "body length", "body_width": "body width",
+         "lead_span": "lead span", "ep_length": "exposed pad length", "ep_width": "exposed pad width",
+         "has_ep": "exposed pad", "package_type": "package type", "pins": "pin numbers", "pin_names": "pin names"}
+_LABEL_TO_FIELD = {"pin count": "pin_count", "pitch": "pitch", "body length": "body_length", "body width": "body_width",
+                   "lead span": "lead_span", "exposed pad length": "ep_length", "exposed pad width": "ep_width",
+                   "exposed pad": "has_ep", "package type": "package_type", "pin numbers": "pins", "pin names": "pin_names"}
+_CC = re.compile(r"^(?:(?P<against>.*): )?(?P<label>[a-z ]+?) read (?P<first>.+?), (?P<src>table|second read) (?P<second>.+)$")
+_PAR = re.compile(r"^(?P<what>.+?): KiCad (?P<kicad>.+?) / Altium (?P<altium>.+?)(?: \((?P<note>.*)\))?$")
+SVG_MAX = 60_000                                  # a footprint picture bigger than this is left out of the list
+
+
+# ------------------------------------------------------------------ held reasons in plain words
+def reason(raw):
+    """One hold reason -> {code, text, fix, detail} in the shared voice (ecadlib.messages); detail is the machine
+    wording, kept for reports and JSON."""
+    e = M.explain(raw)
+    return {"code": e["code"], "text": e["text"] + (f" ({e['note']})" if e.get("note") else ""), "fix": e["fix"], "detail": raw}
+
+
+# ------------------------------------------------------------------ cross-check, parity, datasheet, cost
+def _num(s):
+    m = re.match(r"\s*(-?\d+(?:\.\d+)?)", str(s))
+    return m and m.group(1)
+
+
+def cross_check(rec, sidecar=None):
+    """Plan item cross_check {status, summary} (+ the read's sidecar, when written) -> what the panel shows:
+    {status, label, rows: [{field, label, first, second, against, page}], summary}."""
+    if not rec:
+        return None
+    st = rec.get("status") or "unchecked"
+    label = {"agreed": "agrees with a second source", "disagreed": "two sources disagree",
+             "unchecked": "not cross-checked", "skipped": "not needed (footprint from another source)"}.get(st, st)
+    rows = []
+    full = (sidecar or {}).get("cross_check") or {}
+    dims = (sidecar or {}).get("dimensions") or {}
+    page = lambda f: (dims.get(f) or {}).get("page") if isinstance(dims.get(f), dict) else None
+    if full.get("checks"):
+        for c in full["checks"]:
+            for d in c.get("disagreed") or []:
+                rows.append({"field": d["field"], "label": FIELD.get(d["field"], d["field"]), "first": d["first"],
+                             "second": d["second"], "against": c.get("against") or c.get("source") or "",
+                             "second_is": "table" if c.get("source") == "standard table" else "second read",
+                             "page": page(d["field"])})
+    else:
+        against = ""
+        for seg in (rec.get("summary") or "").split("; "):
+            m = _CC.match(seg)
+            if not m:
+                continue
+            against = m.group("against") or against
+            f = _LABEL_TO_FIELD.get(m.group("label").strip(), m.group("label").strip())
+            rows.append({"field": f, "label": FIELD.get(f, m.group("label")), "first": m.group("first"),
+                         "second": m.group("second"), "against": against, "second_is": m.group("src"), "page": page(f)})
+    out = {"status": st, "label": label, "rows": rows, "summary": rec.get("summary") or ""}
+    if st == "disagreed" and rows:
+        r = rows[0]
+        text, fix = M.held("crosscheck.disagree", field=r["label"], first=r["first"], second=r["second"],
+                           other=r["second_is"], page=r["page"])
+        out["reason"] = {"code": "crosscheck.disagree", "text": text, "fix": fix, "detail": "cross-check disagrees: " + out["summary"]}
+    return out
+
+
+def parity(item):
+    """{result: match | mismatch | None, rows: [{what, kicad, altium}]} from the release check's parity rule."""
+    rc = item.get("release_check") or {}
+    res = rc.get("parity")
+    rows = []
+    for m in list(item.get("hold_reasons") or []) + [w for w in rc.get("warnings") or []]:
+        rule, _, msg = m.partition(": ")
+        if rule != "parity":
+            continue
+        p = _PAR.match(re.sub(r" \((cannot be overridden|not covered by --allow)\)$", "", msg))
+        rows.append({"what": p.group("what"), "kicad": p.group("kicad"), "altium": p.group("altium")} if p
+                    else {"what": msg, "kicad": "", "altium": ""})
+    if rows and not res:
+        res = "mismatch"
+    return {"result": res, "label": {"match": "KiCad and Altium match", "mismatch": "KiCad and Altium differ"}.get(res, "not compared"),
+            "rows": rows}
+
+
+def datasheet_url(item):
+    params = {p.get("name"): p.get("value") for p in item.get("parameters") or [] if isinstance(p, dict)}
+    for k, v in params.items():
+        m = re.fullmatch(r"ComponentLink(\d+)Description", k or "")
+        if m and str(v).strip().lower() == "datasheet":
+            u = params.get(f"ComponentLink{m.group(1)}URL")
+            if u:
+                return u
+    return params.get("Datasheet") or params.get("datasheet") or None
+
+
+def _sidecar(out, name):
+    d = Path(out) / "datasheet"
+    if not d.is_dir():
+        return None
+    safe = re.sub(r"[^A-Za-z0-9._-]+", "_", name)
+    for f in (d / f"{name}.extraction.json", d / f"{safe}.extraction.json"):
+        try:
+            if f.is_file() and f.resolve().parent == d.resolve():
+                v = json.loads(f.read_text(encoding="utf-8"))
+                return v if isinstance(v, dict) else None
+        except (OSError, ValueError):
+            return None
+    return None
+
+
+def costs(out):
+    """What the datasheet reads of this plan cost so far: totals and per part (from datasheet/cost.jsonl)."""
+    from . import ds_route as DR
+    recs = DR.read_ledger(Path(out) / "datasheet" / "cost.jsonl")
+    s = DR.summarize(recs)
+    return {"answers": s["answers"], "usd": round(s["usd"] + s["usd_estimated"], 4), "usd_estimated": s["usd_estimated"],
+            "models": sorted(m for m in s["by_model"] if m and m != "?"), "by_part": s["by_part"],
+            "tokens": s["input_tokens"] + s["output_tokens"]}
+
+
+def _picture(out, item):
+    """Small top-view SVG of the footprint (from its .kicad_mod), or None."""
+    km = (item.get("footprint") or {}).get("kicad_mod")
+    if not km:
+        return None
+    f = (Path(out) / km)
+    try:
+        if not f.is_file() or Path(out).resolve() not in f.resolve().parents:
+            return None
+        from .app import footprint_svg
+        svg = footprint_svg(None, 12, f.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return svg if len(svg) <= SVG_MAX else None
+
+
+def _pads(svg):
+    return len(re.findall(r'class="pad[ "]', svg or ""))
+
+
+def _decisions(approvals):
+    """Recorded decisions without an approvals.json policy: who approved last (a later reject takes it back)."""
+    last = {}
+    for a in approvals or []:
+        if isinstance(a, dict) and a.get("who"):
+            last[a.get("key") or a["who"]] = a
+    ok = [a["who"] for a in last.values() if a.get("decision") == "approve"]
+    no = [a["who"] for a in last.values() if a.get("decision") == "reject"]
+    if not ok and not no:
+        return None
+    return {"required": False, "met": None, "approved_by": ok, "rejected_by": no, "missing": [], "stale": []}
+
+
+# ------------------------------------------------------------------ the cards
+def cards(out, items, pictures=True):
+    """out: the librarian folder of a BOM (plan.json, models/, datasheet/); items: the plan. -> {parts, counts, cost}."""
+    from . import librarian as L
+    cost = costs(out)
+    review = {r["part"]: r for r in L.review_rows(items)}
+    parts = []
+    for it in items:
+        name, st = it["name"], it.get("status") or ""
+        sc = _sidecar(out, name) if it.get("cross_check") else None
+        cc = cross_check(it.get("cross_check"), sc)
+        reasons = []
+        for h in it.get("hold_reasons") or []:
+            if cc and cc.get("reason") and h.startswith("cross-check"):     # said once, with both values
+                continue
+            reasons.append(reason(h))
+        if cc and cc["status"] == "disagreed" and cc.get("reason"):
+            reasons.insert(0, cc["reason"])
+        elif st == "held" and not reasons:
+            reasons = [reason(x) for x in (review.get(name, {}).get("why") or "").split("; ") if x][:3]
+        appr = it.get("approval") or None
+        if st == "awaiting_approval" and appr:
+            for m in appr.get("missing") or []:
+                reasons.append(reason(f"awaiting approval: {m}"))
+        pc = cost["by_part"].get(name) or {}
+        svg = _picture(out, it) if pictures else None
+        url = datasheet_url(it)
+        page = next((r["page"] for r in (cc or {}).get("rows", []) if r.get("page")), None) or \
+            ((sc or {}).get("pin_table") or {}).get("page")
+        parts.append({
+            "part": name, "folder": it.get("folder") or "", "description": it.get("description") or "",
+            "status": st, "status_label": M.status_word(st),
+            "allowed": bool(it.get("allow")), "duplicate_of": it.get("duplicate_of"),
+            "reasons": reasons,
+            "symbol": {"ref": (it.get("symbol") or {}).get("ref"), "found": bool((it.get("symbol") or {}).get("file")),
+                       "from": (it.get("source") or {}).get("symbol") or ""},
+            "footprint": {"ref": (it.get("footprint") or {}).get("ref"), "found": bool((it.get("footprint") or {}).get("file")),
+                          "from": (it.get("source") or {}).get("footprint") or "", "pads": _pads(svg) or None},
+            "picture": svg,
+            "cross_check": cc, "parity": parity(it),
+            "datasheet": {"url": url, "page": page} if url else None,
+            "cost": {"usd": round(pc.get("usd", 0.0), 4), "models": [m for m in pc.get("models") or [] if m],
+                     "answers": pc.get("answers", 0)} if pc else None,
+            "approval": {k: appr.get(k) for k in ("required", "met", "approved_by", "missing", "stale")} if appr
+            else _decisions(it.get("approvals")),
+            "tried": (it.get("librarian") or {}).get("tried") or [],
+        })
+    counts = {"parts": len(parts), "ready": sum(p["status"] == "ready" for p in parts),
+              "held": sum(p["status"] == "held" for p in parts),
+              "waiting": sum(p["status"] == "awaiting_approval" for p in parts),
+              "cross_check_disagreed": sum(bool(p["cross_check"]) and p["cross_check"]["status"] == "disagreed" for p in parts),
+              "parity_mismatch": sum(p["parity"]["result"] == "mismatch" for p in parts)}
+    return {"parts": parts, "counts": counts,
+            "cost": {k: cost[k] for k in ("answers", "usd", "usd_estimated", "models", "tokens")}}

ecadlib/plugins.py

@@ -0,0 +1,231 @@
+"""Plugins: third-party part sources and exporters, installed as ordinary Python packages and found through entry points.
+
+    ecadlib plugins list                              built-in and installed providers and exporters (and load errors)
+    ecadlib plugins export NAME PLAN.json -o DIR      run an exporter plugin on a librarian plan
+
+Part sources (entry point group `ecadlib.providers`): the object is a class like the built-in ones in
+ecadlib/providers.py:
+
+    class MyDistributor(ecadlib.providers.Provider):
+        name = "mydist"                  # what [providers] order and --providers call it
+        auth = "API key in MYDIST_KEY"   # shown in reports and the UI
+        env = ("MYDIST_KEY",)            # configured() is True when these are set
+        def lookup(self, line):          # line: the BOM line dict (mpn, manufacturer, lcsc, value, footprint, ...)
+            r = self.http.get(...)       # self.http: ecadlib's cached, rate-limited HTTP client
+            return SourceResult(self.name, found=True, mpn=..., has_symbol=True, has_footprint=True, url=...)
+
+raise NotConfigured when credentials are missing; any other exception from a plugin becomes a note on that BOM line
+(a broken plugin never stops a triage). Triage asks the providers in order and stops at the first one that has a
+footprint.
+
+Exporters (entry point group `ecadlib.exporters`): the object is a callable, or an object with an `export` method,
+called as export(items, out_dir, rules) -> list of written paths. items: the plan items (plan.json), out_dir: a Path
+that exists, rules: the loaded library rules. Optional attributes: name, description.
+
+[providers] order = ["mydist", "jlcpcb_search", "easyeda"] chooses and orders the sources for triage, the librarian,
+the web UI / MCP workspace and the library agent; [] (the default) keeps each command's own default. An explicit
+--providers flag still wins. See examples/ecadlib_example_plugin/ for a complete, installable example."""
+import argparse, json, sys
+from pathlib import Path
+
+from . import providers as P
+
+GROUPS = ("ecadlib.providers", "ecadlib.exporters")
+_cache = {}
+
+
+def _entry_points(group):
+    from importlib.metadata import entry_points
+    try:
+        return list(entry_points(group=group))
+    except TypeError:                                   # very old importlib.metadata: a dict of groups
+        return list(entry_points().get(group, []))
+
+
+def load(group, eps=None):
+    """{name: object} for one group, and [(name, error)] for plugins that failed to load. eps: entry points (tests)."""
+    if eps is None and group in _cache:
+        return _cache[group]
+    found, errors = {}, []
+    for ep in (_entry_points(group) if eps is None else eps):
+        try:
+            obj = ep.load()
+        except Exception as e:                          # a broken plugin is reported, never fatal
+            errors.append((ep.name, f"{type(e).__name__}: {e}"))
+            continue
+        found[ep.name] = obj
+    res = (found, errors)
+    if eps is None:
+        _cache[group] = res
+    return res
+
+
+def reset():
+    _cache.clear()
+
+
+def provider_classes(eps=None):
+    """{name: class}: the built-in providers, then plugins (a plugin cannot replace a built-in name). -> (dict, errors)"""
+    out = {c.name: c for c in P.ALL}
+    plugins, errors = load("ecadlib.providers", eps)
+    errors = list(errors)
+    for ep_name, cls in plugins.items():
+        name = getattr(cls, "name", None) or ep_name
+        if not isinstance(cls, type) or not callable(getattr(cls, "lookup", None)):
+            errors.append((ep_name, "not a provider class (needs name, lookup(line))"))
+            continue
+        if name in out:
+            errors.append((ep_name, f"provider name {name!r} is taken by a built-in or another plugin"))
+            continue
+        out[name] = _guarded(cls, name)
+    return out, errors
+
+
+def _guarded(cls, name):
+    """A subclass of plugin class cls whose construction and configured() never raise: a plugin that fails to start
+    (missing config file, bad key ...) answers every lookup with an error note on the line instead of stopping triage,
+    and reports itself as not configured. lookup() errors are turned into notes by bom_triage (_plugin = True)."""
+    def __init__(self, *a, **k):
+        self._plugin_error = None
+        try:
+            cls.__init__(self, *a, **k)
+        except Exception as e:
+            self._plugin_error = f"{type(e).__name__}: {str(e)[:120]}"
+            self.http = a[0] if a else k.get("http")
+
+    def lookup(self, line):
+        if self._plugin_error:
+            raise RuntimeError(f"plugin failed to start: {self._plugin_error}")
+        return cls.lookup(self, line)
+
+    def configured(self):
+        if self._plugin_error:
+            return False
+        try:
+            return bool(cls.configured(self)) if callable(getattr(cls, "configured", None)) else True
+        except Exception:
+            return False
+    return type(cls.__name__, (cls,), {"name": name, "_plugin": True, "auth": str(getattr(cls, "auth", "") or ""),
+                                       "__module__": cls.__module__, "__init__": __init__, "lookup": lookup,
+                                       "configured": configured})
+
+
+def select(names=None, rules=None, default=None, eps=None):
+    """Provider classes in order. names: an explicit choice (list or comma text, e.g. --providers) wins; else the
+    rules' [providers] order when not empty; else default (names; None = every built-in). Unknown names raise
+    ValueError listing what is available; a plugin named in [providers] order that fails to load is skipped with a
+    warning on stderr (an explicit --providers choice of it raises)."""
+    if isinstance(names, str):
+        names = [n.strip() for n in names.split(",") if n.strip()]
+    order = ((rules or {}).get("providers") or {}).get("order") or []
+    want = list(names) if names else list(order) if order else (
+        [n.strip() for n in default.split(",") if n.strip()] if isinstance(default, str) else
+        list(default) if default is not None else [c.name for c in P.ALL])
+    avail, errors = provider_classes(eps)
+    if not names and order:                             # a plugin in the rules' order that fails to load is skipped
+        broken = {n: e for n, e in errors if n in want and n not in avail}      # (with a warning): triage goes on
+        for n, e in broken.items():
+            print(f"ecadlib: [providers] order: plugin {n} skipped, it failed to load: {e}", file=sys.stderr)
+        want = [n for n in want if n not in broken]
+    bad = [n for n in want if n not in avail]
+    if bad:
+        why = "".join(f"; plugin {n} failed to load: {e}" for n, e in errors if n in bad)
+        raise ValueError(f"unknown provider {bad[0]!r}; available: {', '.join(avail)}{why}")
+    if "jlcpcb_search" in want and "easyeda" in want and want.index("jlcpcb_search") > want.index("easyeda"):
+        want.remove("jlcpcb_search")                    # it finds the LCSC number EasyEDA is keyed by: always before it
+        want.insert(want.index("easyeda"), "jlcpcb_search")
+    seen, out = set(), []
+    for n in want:
+        if n not in seen:
+            seen.add(n)
+            out.append(avail[n])
+    return out
+
+
+def order_set(rules):
+    return bool(((rules or {}).get("providers") or {}).get("order"))
+
+
+def exporters(eps=None):
+    """{name: callable(items, out_dir, rules)} and load errors."""
+    found, errors = load("ecadlib.exporters", eps)
+    out, errors = {}, list(errors)
+    for name, obj in found.items():
+        try:
+            target = obj() if isinstance(obj, type) else obj          # a class: one instance with an export method
+        except Exception as e:
+            errors.append((name, f"{type(e).__name__}: {e}"))
+            continue
+        fn = getattr(target, "export", None) or (target if callable(target) else None)
+        if not callable(fn):
+            errors.append((name, "not an exporter (needs export(items, out_dir, rules))"))
+            continue
+        desc = getattr(target, "description", "") or (fn.__doc__ or "").strip().split("\n")[0]
+        out[getattr(target, "name", None) or name] = (fn, desc)
+    return out, errors
+
+
+def run_exporter(name, plan, out_dir, rules=None, eps=None):
+    """Run exporter `name` on a plan (path or list of items). -> list of written paths (as text)."""
+    from . import rules as RU
+    ex, errors = exporters(eps)
+    if name not in ex:
+        why = "".join(f"; {n} failed to load: {e}" for n, e in errors if n == name)
+        raise ValueError(f"unknown exporter {name!r}; installed: {', '.join(ex) or 'none'}{why}")
+    items = json.loads(Path(plan).read_text()) if not isinstance(plan, list) else plan
+    if not isinstance(items, list):
+        raise ValueError(f"{plan}: not a plan (a JSON list of parts)")
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    rules = RU.resolve(rules, Path(plan).parent if not isinstance(plan, list) else out_dir)
+    paths = ex[name][0](items, out_dir, rules) or []
+    return [str(p) for p in paths]
+
+
+def describe(eps_providers=None, eps_exporters=None):
+    provs, perr = provider_classes(eps_providers)
+    ex, eerr = exporters(eps_exporters)
+    return {"providers": [{"name": n, "plugin": bool(getattr(c, "_plugin", False)), "auth": getattr(c, "auth", ""),
+                           "module": c.__module__} for n, c in provs.items()],
+            "exporters": [{"name": n, "description": d} for n, (_, d) in ex.items()],
+            "errors": [{"plugin": n, "error": e} for n, e in perr + eerr]}
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="ecadlib plugins", description="installed part-source and exporter plugins")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    ls = sub.add_parser("list", help="providers and exporters, built-in and installed")
+    ls.add_argument("--json", action="store_true")
+    ex = sub.add_parser("export", help="run an exporter plugin on a librarian plan")
+    ex.add_argument("name")
+    ex.add_argument("plan")
+    ex.add_argument("-o", "--out", required=True, help="output folder")
+    ex.add_argument("--rules", help="ecadlib.toml (default: found from the plan's folder)")
+    a = ap.parse_args(argv)
+    if a.cmd == "list":
+        d = describe()
+        if a.json:
+            print(json.dumps(d, indent=2))
+            return 0
+        print("providers (triage part sources; [providers] order picks and orders them):")
+        for p in d["providers"]:
+            print(f"  {p['name']:<16} {'plugin ' + p['module'] if p['plugin'] else 'built-in':<34} {p['auth'][:60]}")
+        print("exporters (ecadlib plugins export NAME PLAN -o DIR):")
+        for e in d["exporters"] or [{"name": "(none installed)", "description": ""}]:
+            print(f"  {e['name']:<16} {e['description']}")
+        for e in d["errors"]:
+            print(f"  plugin {e['plugin']} failed to load: {e['error']}", file=sys.stderr)
+        return 0
+    try:
+        paths = run_exporter(a.name, a.plan, a.out, a.rules)
+    except (ValueError, OSError) as e:
+        print(f"ecadlib plugins export: {e}", file=sys.stderr)
+        return 2
+    for p in paths:
+        print(p)
+    print(f"{a.name}: {len(paths)} file(s) -> {a.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())