ecadlib 0.3.0__py3-none-any.whl

ecadlib/cfb.py

@@ -0,0 +1,171 @@
+"""Minimal Compound File Binary (OLE2 / MS-CFB) *writer*: version 3, 512-byte sectors.
+
+    write_cfb(path, {"FileHeader": b"...", "Library": {"Header": b"...", "Data": b"..."}})
+
+A dict is a storage, bytes is a stream. Streams under the 4096-byte cutoff live in the mini
+stream (64-byte mini sectors); larger ones in regular sectors. FAT/MiniFAT/DIFAT are built to
+fit, so files past 109 FAT sectors (~7 MB) get DIFAT sectors too.
+
+Directory: each storage's children form a balanced binary search tree ordered the MS-CFB way
+(UTF-16 length first, then upper-cased code units) with every node black. MS-CFB 2.6.4 allows
+this: "the simplest implementation of the above invariants would be to mark every node as
+black, in which case the tree is simply a binary tree". Timestamps and CLSIDs are left zero.
+olefile (BSD) reads files written here; tests/test_offline.py checks it raises no warnings."""
+import struct
+
+SECTOR, MINI, CUTOFF = 512, 64, 4096
+FREESECT, ENDOFCHAIN, FATSECT, DIFSECT, NOSTREAM = 0xFFFFFFFF, 0xFFFFFFFE, 0xFFFFFFFD, 0xFFFFFFFC, 0xFFFFFFFF
+STORAGE, STREAM, ROOT = 1, 2, 5
+
+
+def _units(name):
+    """UTF-16 code units of name (MS-CFB names and their ordering are defined on code units)."""
+    b = name.encode("utf-16-le")
+    return struct.unpack(f"<{len(b) // 2}H", b)
+
+
+def _key(name):
+    # length first, then code units upper-cased one by one (simple case mapping: a unit whose
+    # str.upper() is not a single BMP unit, e.g. 'ß' -> 'SS', is left as is)
+    up = []
+    for u in _units(name):
+        c = chr(u).upper() if not 0xD800 <= u <= 0xDFFF else chr(u)
+        up.append(ord(c) if len(c) == 1 and ord(c) <= 0xFFFF else u)
+    return (len(up), tuple(up))
+
+
+class _Entry:
+    def __init__(self, name, kind, data=b""):
+        if not name or len(_units(name)) > 31 or any(c in name for c in "/\\:!"):
+            raise ValueError(f"illegal CFB name {name!r} (1-31 UTF-16 code units, no / \\ : !)")
+        self.name, self.kind, self.data = name, kind, data
+        self.children = []
+        self.left = self.right = self.child = NOSTREAM
+        self.start, self.size = ENDOFCHAIN, 0
+
+
+def _flatten(tree):
+    """dict tree -> list of _Entry with sibling/child ids (index 0 = root)."""
+    entries = [_Entry("Root Entry", ROOT)]
+
+    def add(parent, node):
+        for name, val in node.items():
+            e = _Entry(name, STORAGE if isinstance(val, dict) else STREAM, b"" if isinstance(val, dict) else bytes(val))
+            entries.append(e); parent.children.append(len(entries) - 1)
+            if isinstance(val, dict):
+                add(e, val)
+        keys = [_key(entries[i].name) for i in parent.children]
+        if len(set(keys)) != len(keys):
+            raise ValueError(f"duplicate (case-insensitive) names under {parent.name!r}")
+
+    def balance(ids):                         # sorted ids -> root id of a balanced BST
+        if not ids:
+            return NOSTREAM
+        m = len(ids) // 2
+        e = entries[ids[m]]
+        e.left, e.right = balance(ids[:m]), balance(ids[m + 1:])
+        return ids[m]
+
+    add(entries[0], tree)
+    for e in entries:
+        if e.kind != STREAM:
+            e.child = balance(sorted(e.children, key=lambda i: _key(entries[i].name)))
+    return entries
+
+
+def _chain(fat, first, n):
+    for i in range(n):
+        fat[first + i] = first + i + 1 if i < n - 1 else ENDOFCHAIN
+
+
+def to_bytes(tree):
+    entries = _flatten(tree)
+    streams = [e for e in entries if e.kind == STREAM]
+    mini = bytearray(); minifat = []
+    for e in streams:                         # small streams -> mini stream
+        e.size = len(e.data)
+        if 0 < e.size < CUTOFF:
+            n = -(-e.size // MINI)
+            e.start = len(minifat); _chain_list(minifat, e.start, n)
+            mini += e.data + b"\0" * (n * MINI - e.size)
+    root = entries[0]
+    root.data, root.size = bytes(mini), len(mini)
+
+    # sector plan: [mini stream][big streams][minifat][directory][FAT][DIFAT]
+    big = ([root] if root.size else []) + [e for e in streams if e.size >= CUTOFF]
+    nsec = lambda b: -(-b // SECTOR)
+    data_secs = sum(nsec(e.size) for e in big)
+    n_minifat = nsec(len(minifat) * 4)
+    n_dir = nsec(len(entries) * 128)
+    used = data_secs + n_minifat + n_dir
+    n_fat = n_difat = 0
+    while True:                               # FAT must also map itself and the DIFAT sectors
+        total = used + n_fat + n_difat
+        nf = nsec(total * 4)
+        nd = 0 if nf <= 109 else -(-(nf - 109) // 127)
+        if (nf, nd) == (n_fat, n_difat):
+            break
+        n_fat, n_difat = nf, nd
+    total = used + n_fat + n_difat
+    fat = [FREESECT] * (n_fat * SECTOR // 4)
+
+    pos = 0
+    for e in big:
+        n = nsec(e.size)
+        e.start = pos; _chain(fat, pos, n); pos += n
+    minifat_start = pos if n_minifat else ENDOFCHAIN
+    if n_minifat:
+        _chain(fat, pos, n_minifat); pos += n_minifat
+    dir_start = pos; _chain(fat, pos, n_dir); pos += n_dir
+    fat_secs = list(range(pos, pos + n_fat))
+    for s in fat_secs:
+        fat[s] = FATSECT
+    pos += n_fat
+    difat_secs = list(range(pos, pos + n_difat))
+    for s in difat_secs:
+        fat[s] = DIFSECT
+    assert pos + n_difat == total
+
+    out = bytearray()
+    hdr = bytearray(b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1" + b"\0" * 16)
+    hdr += struct.pack("<HHHHH6sIIIIIIIII", 0x3E, 3, 0xFFFE, 9, 6, b"\0" * 6, 0, n_fat, dir_start, 0, CUTOFF,
+                       minifat_start, n_minifat, difat_secs[0] if difat_secs else ENDOFCHAIN, n_difat)
+    hdr += struct.pack("<109I", *(fat_secs[:109] + [FREESECT] * (109 - min(109, n_fat))))
+    out += hdr
+
+    for e in big:
+        out += e.data + b"\0" * (-len(e.data) % SECTOR)
+    mf = struct.pack(f"<{len(minifat)}I", *minifat)
+    out += mf + b"\xff" * (-len(mf) % SECTOR)          # unused MiniFAT slots = FREESECT
+    d = b"".join(_dirent(e) for e in entries)
+    d += _dirent(None) * ((-len(d) % SECTOR) // 128)
+    out += d
+    out += struct.pack(f"<{len(fat)}I", *fat)
+    rest = fat_secs[109:]
+    for i, s in enumerate(difat_secs):        # 127 FAT-sector ids + next-DIFAT pointer
+        chunk = rest[i * 127:(i + 1) * 127]
+        nxt = difat_secs[i + 1] if i + 1 < len(difat_secs) else ENDOFCHAIN
+        out += struct.pack("<128I", *(chunk + [FREESECT] * (127 - len(chunk)) + [nxt]))
+    assert len(out) == SECTOR * (1 + total), (len(out), total)
+    return bytes(out)
+
+
+def _chain_list(lst, first, n):
+    lst.extend(first + i + 1 if i < n - 1 else ENDOFCHAIN for i in range(n))
+
+
+def _dirent(e):
+    if e is None:                             # unused slot
+        return b"\0" * 64 + struct.pack("<HBBIII16sIQQIQ", 0, 0, 0, NOSTREAM, NOSTREAM, NOSTREAM, b"\0" * 16, 0, 0, 0, 0, 0)
+    nm = (e.name + "\0").encode("utf-16-le")
+    start = 0 if e.kind == STORAGE else (e.start if e.size else ENDOFCHAIN)
+    return (nm + b"\0" * (64 - len(nm)) +
+            struct.pack("<HBBIII16sIQQIQ", len(nm), e.kind, 1, e.left, e.right, e.child,
+                        b"\0" * 16, 0, 0, 0, start, e.size))
+
+
+def write_cfb(path, tree):
+    data = to_bytes(tree)
+    with open(path, "wb") as f:
+        f.write(data)
+    return len(data)

ecadlib/cli.py

@@ -0,0 +1,185 @@
+"""One command for everything:  ecadlib <command> [options]   (or: python -m ecadlib <command>)
+
+    ecadlib setup                                 the setup page in your browser: AI model + key, Altium / KiCad, folders
+    ecadlib start                                 the desktop app (what the Windows Start menu entry runs)
+    ecadlib keys      list|set NAME|remove NAME   API keys stored for you (encrypted on Windows), instead of env variables
+    ecadlib init      [--yes] [--tool T] [--lib DIR] [--from DIR ...]   set up: tool, libraries, workspace, sources -> ecadlib.toml, doctor
+    ecadlib demo      [-o DIR]                    a small library from a bundled BOM, offline, no keys (start here)
+    ecadlib rules     check|show                  validate the rules file / print the defaults
+    ecadlib style     learn|show|direct|check|apply|export-dataset   learn your house style from your library + your direction
+    ecadlib ui        --lib <kicad libs>          local web UI in your browser (--team: shared server with sign-in)
+    ecadlib team      add-user|set-role|reset-password|remove|list|setup   users and roles for `ecadlib ui --team`; setup: Docker + HTTPS
+    ecadlib mcp       --lib <kicad libs>          MCP server (stdio) for Claude and other agents
+    ecadlib triage    BOM --lib ... -o out/x      BOM triage report (.md + .csv)
+    ecadlib footprint gen|compare ...             IPC-7351B footprint generator (also BGA, pin headers, connectors, pad tables)
+    ecadlib footprint-bench [--offline]           compare generated footprints with KiCad's official ones, pad by pad
+    ecadlib eval      run|compare|sets|show ...   accuracy test set: run the pipeline on known parts, pass rate and cost
+    ecadlib dblib     BOM -o out/altium           Altium DbLib (SQLite + XLSX + .DbLib)
+    ecadlib altium-lib pcblib|schlib|dump ...     write/read Altium .PcbLib/.SchLib files
+    ecadlib altium365 plan|workspaces|push ...    Altium 365 release via Nexar
+    ecadlib dblib-sync plan.json --to DIR [--svn] Altium without 365: sync a plan into a .DbLib/.SVNDbLib folder
+    ecadlib librarian BOM --lib ... -o out/lib    BOM -> missing parts filled -> Altium models + plan + review
+    ecadlib datasheet PDF --part MPN | batch PLAN|BOM | estimate PLAN|BOM   Claude reads datasheets -> symbols + footprints
+    ecadlib release-check plan.json [--allow P]   hold back plan items that fail the pre-release checks
+    ecadlib kicad-export plan.json -o DIR --name LIB   the same library as KiCad files (.kicad_sym, .pretty)
+    ecadlib eagle-export plan.json -o DIR --name LIB   the same library for Autodesk Fusion Electronics / EAGLE (.lbr)
+    ecadlib easyeda-export plan.json -o DIR --name LIB the same library for EasyEDA Pro (.elibz)
+    ecadlib resolve   plan.json [--part P] list|show|choose ...   fix held parts: ranked candidates, pick one
+    ecadlib review    [plan.json] [--part P] [--yes]   go through held parts one by one: why, pick a candidate, release anyway
+    ecadlib upstream  check-kicad|check-a365 ...  upstream change alerts (KiCad sources, Altium 365 drift)
+    ecadlib a365      pull|status|reconcile PLAN --workspace URL [--state F]   two-way Altium 365 sync
+    ecadlib queue     list|show|approve|reject|rebuild|retry [ID]   the library agent's review queue
+    ecadlib approve   plan.json approve|reject|status [--part P]   sign-off before altium365 push
+    ecadlib dedupe    plan.json [--lib ...] [--merge]  duplicate parts, footprints and symbols
+    ecadlib sourcing  BOM [--qty N] [--alternates] price, stock, second sources and alternates per BOM line
+    ecadlib project   BOARD.PrjPcb [-o bom.csv] [--variant V]   BOM straight from an Altium project (.PrjPcb/.SchDoc)
+    ecadlib where-used --projects DIR... [--part X] [--plan plan.json]   which projects use which library part
+    ecadlib step-gen  SPEC.json|FOOTPRINT -o x.step   package-shaped 3D model (STEP); --check FILE.step validates
+    ecadlib upkeep    PLAN|BOM [--checks ...] [--apply] [--github issue|pr]   weekly checks, only what is new, one issue/PR
+    ecadlib sim-models plan.json [--models DIR] [--attach]   find, check and attach SPICE / IBIS simulation models
+    ecadlib agent-watch [--dry-run] [--source TYPE:REF]   library agent: new / changed / removed parts in watched projects and BOMs
+    ecadlib agent     run [--dry-run]|serve|status|approve ID|reject ID|push   library agent: watch, build, prove, PR, push
+    ecadlib symbol    PINS.csv|PART -o x.SchLib [--preview x.svg]   big-chip symbol with pins grouped by function
+    ecadlib visual-check PART|x.kicad_mod --datasheet DS.pdf [--pages 3,7-8]   Claude compares our drawings with the datasheet
+    ecadlib doctor    [--workspace W] [--lib DIR] [--json]   check Python, packages, API keys, ecadlib.toml, folders
+    ecadlib status    [--workspace W] [--json]    one-screen summary of a workspace: parts, held, sign-off, last runs
+    ecadlib completion bash|zsh|fish              shell completion script (e.g. ecadlib completion bash > ~/.ecadlib.bash)
+    ecadlib plugins   list|export NAME PLAN -o DIR   installed part-source / exporter plugins (Python entry points)
+    ecadlib notify    show|test [--event E]       [notify] webhooks (Slack, Teams, JSON): targets, send a test message
+    ecadlib kicad-dblib plan.json -o DIR --name LIB [--export]   KiCad database library (.kicad_dbl + SQLite)
+    ecadlib export-parts plan.json --format csv|json|xlsx [-o F]   parts table with stable columns (PLM / ERP)
+    ecadlib stdparts resolve "SOIC-8 3.9x4.9mm" | coverage BOM | bench   standard packages built offline (librarian source)
+    ecadlib kicad-pcm plan.json|KICAD_DIR --out DIR [--kicad 7]   KiCad Plugin and Content Manager zip (--plugin: action plugin)
+    ecadlib altium-pkg plan.json|MODELS_DIR --out DIR   Altium .LibPkg (-> IntLib), install script, relative DbLib
+    ecadlib altium-menu build --out DIR [--win-dir W]   an "ecadlib" menu inside Altium (script project): add part, check BOM, queue
+    ecadlib kicad-menu check-bom NETLIST|SCH     what the ecadlib window in KiCad runs; Generate BOM hook for the schematic
+    ecadlib costs     [--model M] [--all] [--md F] [--xlsx F]   estimated AI cost per job, for your model or every model
+    ecadlib ai        show [--model M] [--detect] | rails   which model / provider / guide rails the AI features use
+    ecadlib migrate   [PATH] [--check] [--dry-run]   check / upgrade workspace files to this version (backups first)
+    ecadlib rebuild   LIB_DIR [--check]           rebuild a library from library.lock.json offline; report drift
+    ecadlib testpack  --out DIR                   small Altium + KiCad test pack (6 parts) + CHECKLIST.md for a person to open
+    ecadlib parity    plan.json [--kicad DIR] [--altium DIR] | pair A B | survey   KiCad and Altium files of every part match
+
+`ecadlib <command> -h` shows that command's options. -q / --quiet prints only the outcome, -v / --verbose every
+detail; colour only on a terminal (NO_COLOR=1 or ECADLIB_COLOR=never turns it off). --debug (or ECADLIB_DEBUG=1) shows tracebacks instead of a
+one-line error. ECADLIB_LIB, ECADLIB_WORKSPACE and ECADLIB_CONFIG are defaults for --lib, --workspace and the rules file."""
+import importlib, sys
+
+COMMANDS = {
+    "setup": ("ecadlib.easy_setup", "open the setup page: AI model and key, Altium / KiCad, folders, add ecadlib to Altium and KiCad"),
+    "start": ("ecadlib.launcher", "the desktop app: start ecadlib in the background and open it in the browser (setup page on first run)"),
+    "keys": ("ecadlib.userconfig", "API keys stored for this user instead of environment variables: list, set, remove"),
+    "init": ("ecadlib.rules_infer", "set up ecadlib: tool, library folders, workspace, sources; learn your conventions -> ecadlib.toml"),
+    "demo": ("ecadlib.firstrun:demo_main", "build a small library from a bundled sample BOM, offline, no API keys"),
+    "rules": ("ecadlib.rules", "check or show the library rules"),
+    "style": ("ecadlib.house_style", "learn your house style from your library and your written direction; new parts follow it"),
+    "ui": ("ecadlib.ui.server", "local web UI"),
+    "team": ("ecadlib.team", "users and roles for the team web server (ecadlib ui --team)"),
+    "mcp": ("ecadlib.mcp_server", "MCP server over stdio"),
+    "triage": ("ecadlib.bom_triage", "BOM triage report"),
+    "footprint": ("ecadlib.footprint_gen", "IPC-7351B footprint generator"),
+    "check": ("ecadlib.footprint_rules", "check .kicad_mod files against the footprint rule book (KLC / IPC-7351)"),
+    "footprint-bench": ("ecadlib.footprint_bench", "compare generated footprints (BGA, connectors, ...) with KiCad's official ones"),
+    "eval": ("ecadlib.eval.cli", "accuracy test set: run the pipeline on parts with a known answer, score, compare runs"),
+    "dblib": ("ecadlib.altium_export", "Altium DbLib export"),
+    "altium-lib": ("ecadlib.altium_lib", "Altium .PcbLib/.SchLib writer"),
+    "altium365": ("ecadlib.altium365", "Altium 365 release via Nexar"),
+    "dblib-sync": ("ecadlib.altium_dblib_sync", "sync a plan into an Altium .DbLib / .SVNDbLib library folder"),
+    "librarian": ("ecadlib.librarian", "BOM to library: fill missing parts, plan, release check"),
+    "costs": ("ecadlib.costs", "estimated AI cost per job (datasheet read, BOM, library) for your model or every model"),
+    "datasheet": ("ecadlib.datasheet", "Claude datasheet reader: one PDF, or a whole plan/BOM as one Message Batch"),
+    "release-check": ("ecadlib.release_check", "pre-release checks on an altium365 plan"),
+    "kicad-export": ("ecadlib.kicad_export", "librarian plan -> KiCad .kicad_sym / .pretty / .3dshapes"),
+    "eagle-export": ("ecadlib.eagle_export", "librarian plan -> Autodesk Fusion Electronics / EAGLE .lbr, read back pad by pad"),
+    "easyeda-export": ("ecadlib.easyeda_pro_export", "librarian plan -> EasyEDA Pro device library .elibz, read back pad by pad"),
+    "resolve": ("ecadlib.resolve", "fix held parts: candidates for a missing symbol/footprint, choose one"),
+    "review": ("ecadlib.review_cli", "go through held parts one at a time: the reason in plain words, pick a candidate, release anyway, open the datasheet"),
+    "upstream": ("ecadlib.upstream", "KiCad upstream changes and Altium 365 drift"),
+    "a365": ("ecadlib.a365_sync", "two-way Altium 365 sync: pull workspace components into the plan, status, reconcile"),
+    "queue": ("ecadlib.agent_queue", "the library agent's review queue: list, show, approve, reject, rebuild"),
+    "approve": ("ecadlib.approvals", "approve / reject plan items before release"),
+    "dedupe": ("ecadlib.dedupe", "find and merge duplicate parts, footprints and symbols"),
+    "sourcing": ("ecadlib.sourcing", "price, stock, second sources and alternates for a BOM"),
+    "step-gen": ("ecadlib.step_gen", "package-shaped STEP 3D models from a package spec or footprint name"),
+    "upkeep": ("ecadlib.upkeep", "weekly lifecycle / upstream / price / A365 checks; new changes as one issue or PR"),
+    "project": ("ecadlib.altium_project", "BOM straight from an Altium project (.PrjPcb / .SchDoc / ActiveBOM)"),
+    "hub": ("ecadlib.hub", "your library across tools: every part once, a column per tool, last changed and by whom"),
+    "where-used": ("ecadlib.altium_project:where_used_main", "which projects use which library part, and flags"),
+    "sim-models": ("ecadlib.sim_models", "find, check and attach SPICE / IBIS simulation models for a plan"),
+    "agent-watch": ("ecadlib.agent_watch", "library agent watch step: new / changed / removed parts in watched projects and BOMs"),
+    "agent": ("ecadlib.agent", "library agent: watch projects, build + prove parts, batch PRs, push approved parts, upkeep"),
+    "visual-check": ("ecadlib.visual_check", "render footprint/symbol + datasheet pages; Claude checks they match"),
+    "symbol": ("ecadlib.symbol_layout", "IC symbol with pins grouped by function (power, ports, debug ...), SVG preview"),
+    "doctor": ("ecadlib.doctor", "check the setup: Python, packages, API keys (names only), ecadlib.toml, folders"),
+    "status": ("ecadlib.ws_status", "one-screen summary of a workspace: parts, held, waiting for sign-off, last runs"),
+    "completion": ("ecadlib.completion", "shell completion script for bash, zsh or fish"),
+    "plugins": ("ecadlib.plugins", "installed part-source and exporter plugins; run an exporter on a plan"),
+    "notify": ("ecadlib.notify", "webhook notifications ([notify]): show targets, send a test message"),
+    "kicad-dblib": ("ecadlib.kicad_dblib", "KiCad database library: .kicad_dbl (ODBC) + SQLite parts table from a plan"),
+    "export-parts": ("ecadlib.parts_export", "parts table with stable columns as CSV / JSON / XLSX for PLM / ERP imports"),
+    "kicad-pcm": ("ecadlib.kicad_pcm", "package the library for KiCad's Plugin and Content Manager (zip); --plugin: the add-part action plugin"),
+    "altium-pkg": ("ecadlib.altium_pkg", "Altium hand-off folder: .LibPkg to compile an IntLib, install script project, relative DbLib"),
+    "altium-menu": ("ecadlib.altium_menu", "an 'ecadlib' menu inside Altium: DelphiScript project (add part from MPN, check the project BOM, review queue)"),
+    "kicad-menu": ("ecadlib.kicad_menu", "what the ecadlib window in KiCad's PCB editor runs (add part, check BOM, fill, queue)"),
+    "ai": ("ecadlib.llm.cli", "bring your own model: provider, model, key variable, capability profile, guide rails"),
+    "testpack": ("ecadlib.testpack", "write a 6-part Altium + KiCad test pack with a CHECKLIST.md of what to open and what to see"),
+    "migrate": ("ecadlib.migrate", "check or upgrade a workspace's files to this ecadlib's formats (backups first)"),
+    "rebuild": ("ecadlib.rebuild", "rebuild a library from its library.lock.json offline; --check reports any drift"),
+    "parity": ("ecadlib.parity", "read back the KiCad and the Altium library and compare every part (pads, drills, 3D, pins, fields)"),
+    "stdparts": ("ecadlib.stdparts", "standard packages and pinouts without Claude: resolve, list, bench vs KiCad, BOM coverage"),
+}
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    from .cliutil import debug_wanted, env_defaults, report
+    debug, argv = debug_wanted(argv)
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(__doc__)
+        return 0
+    if argv[0] in ("-V", "--version"):
+        from . import __version__
+        print(f"ecadlib {__version__}")
+        return 0
+    cmd = COMMANDS.get(argv[0])
+    if not cmd:
+        print(f"ecadlib: unknown command {argv[0]!r}. Commands: {', '.join(COMMANDS)}", file=sys.stderr)
+        return 2
+    from . import term, userconfig
+    userconfig.apply_env()                                   # keys from `ecadlib keys` / the setup page; env vars win
+    rest = term.set_from_argv(argv[1:])                      # -q / -v for every command; --json: never styled
+    args, notes = env_defaults(argv[0], rest)                # ECADLIB_LIB / ECADLIB_WORKSPACE when the flag is not given
+    from . import firstrun as FR
+    args, more = FR.config_defaults(argv[0], args)          # then ecadlib.toml [setup] libs / workspace
+    notes += more
+    bad = FR.preflight(argv[0], args)                        # a --lib that does not exist, an unwritable -o
+    if bad:
+        print(f"ecadlib {argv[0]}: {bad[0]}\n  hint: {bad[1]}", file=sys.stderr)
+        return 2
+    if debug and notes:
+        print(f"ecadlib {argv[0]}: " + ", ".join(notes), file=sys.stderr)
+    sys.argv = [f"ecadlib {argv[0]}"] + args                 # so argparse usage lines show the right command
+    mod, _, fn = cmd[0].partition(":")
+    from .rules import RulesError
+    try:
+        from .clihelp import installed                       # descriptions + examples in every -h
+        with installed(argv[0], cmd[1]):
+            return getattr(importlib.import_module(mod), fn or "main")(args)
+    except RulesError as e:                                  # a bad ecadlib.toml: say which key, no traceback
+        if debug:
+            raise
+        print(f"ecadlib {argv[0]}: {e}\n  hint: `ecadlib doctor` shows the file and line", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        if debug:
+            raise
+        print(f"ecadlib {argv[0]}: interrupted", file=sys.stderr)
+        return 130
+    except Exception as e:                                   # one line + hint; --debug / ECADLIB_DEBUG=1: the traceback
+        if debug:
+            raise
+        return report(argv[0], e, sys.stderr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ecadlib/clihelp.py

@@ -0,0 +1,149 @@
+"""`ecadlib <command> -h` polish, applied by ecadlib/cli.py to whatever parser the command builds:
+
+- every command and subcommand gets a one-line description (a subcommand without one takes its `help=` text, a
+  command without one takes its line in cli.COMMANDS);
+- every command's help ends with a few examples (EXAMPLES below), so a new user can copy a working line.
+
+Done from the outside (a wrapper around ArgumentParser.parse_known_args while the command runs), so the commands'
+own modules stay as they are and `python -m ecadlib.<module>` still works. tests/test_firstrun.py walks the whole
+argparse tree and checks every command has a description, examples and the common flag spellings."""
+import argparse, types
+
+EXAMPLES = {
+    "init": ["ecadlib init                                   # questions: tool, library folders, workspace, sources",
+             "ecadlib init --yes --tool kicad --lib ~/kicad/libs --workspace ws",
+             "ecadlib init --from ~/altium/libs --yes         # also learn naming / parameters from existing libraries"],
+    "demo": ["ecadlib demo", "ecadlib demo -o /tmp/try --tool kicad"],
+    "kicad-pcm": ["ecadlib kicad-pcm out/librarian/plan.json -o out/pcm --name mylib",
+                  "ecadlib kicad-pcm out/kicad -o out/pcm --kicad 7", "ecadlib kicad-pcm --plugin -o out/pcm"],
+    "altium-menu": ["ecadlib altium-menu build --out out/altium_menu --workspace D:/ecadlib-ws --win-dir D:\\ecadlib-menu",
+                    "ecadlib altium-menu add-part LM358DR --manufacturer TI --workspace D:/ecadlib-ws --result-file r.ini"],
+    "kicad-menu": ["ecadlib kicad-menu run-job JOB --action add-part --project board.kicad_pcb --mpn LM358DR",
+                   "ecadlib kicad-menu check-bom board.kicad_sch --no-open"],
+    "altium-pkg": ["ecadlib altium-pkg out/librarian/plan.json --out out/altium_pkg --name mylib",
+                   "ecadlib altium-pkg out/altium_models --out out/altium_pkg"],
+    "testpack": ["ecadlib testpack --out altium_kicad_testpack"],
+    "costs": ["ecadlib costs", "ecadlib costs --model gemini-3.8-flash", "ecadlib costs --all --md docs/costs.md --xlsx costs.xlsx"],
+    "ai": ["ecadlib ai show", "ecadlib ai show --model qwen2.5:7b --detect", "ecadlib ai rails"],
+    "rules": ["ecadlib rules check", "ecadlib rules check ecadlib.toml", "ecadlib rules show"],
+    "style": ["ecadlib style learn --from ~/altium/libs           # learn your conventions -> house_style.json",
+              "ecadlib style direct \"IC descriptions start with the function in capitals\"",
+              "ecadlib style learn --ai --model qwen2.5:7b    # a model (here a local one) writes the guide from your direction",
+              "ecadlib style check out/librarian/plan.json", "ecadlib style apply out/librarian/plan.json --ai --dry-run",
+              "ecadlib style export-dataset -o train.jsonl --eval-share 0.1"],
+    "ui": ["ecadlib ui", "ecadlib ui --lib ~/kicad/libs --workspace ws", "ecadlib ui --team --host 0.0.0.0"],
+    "team": ["ecadlib team add-user alice --role librarian", "ecadlib team list", "ecadlib team setup --domain lib.example.com"],
+    "mcp": ["claude mcp add ecadlib -- ecadlib mcp --lib ~/kicad/libs --workspace ws"],
+    "triage": ["ecadlib triage my_bom.csv -o out/triage", "ecadlib triage my_bom.csv --lib ~/kicad/libs --offline --json"],
+    "footprint": ["ecadlib footprint gen ecadlib/package_specs/soic8.json -o out/fp",
+                  "ecadlib footprint compare out/fp/SOIC-8.kicad_mod ref/SOIC-8.kicad_mod"],
+    "check": ["ecadlib check out/fp/*.kicad_mod"],
+    "footprint-bench": ["ecadlib footprint-bench --offline", "ecadlib footprint-bench --json bench.json"],
+    "eval": ["ecadlib eval sets", "ecadlib eval run --set kicad-v1 --limit 5 --offline", "ecadlib eval compare runA.json runB.json",
+             "ecadlib eval gate", "ecadlib eval golden --update"],
+    "dblib": ["ecadlib dblib my_bom.csv -o out/altium"],
+    "altium-lib": ["ecadlib altium-lib pcblib specs/SOIC-8_3.9x4.9mm_P1.27mm.json -o out/altium", "ecadlib altium-lib dump x.PcbLib"],
+    "altium365": ["ecadlib altium365 plan my_bom.csv -o out/a365/plan.json", "ecadlib altium365 push out/a365/plan.json --workspace https://acme.365.altium.com --dry-run"],
+    "dblib-sync": ["ecadlib dblib-sync out/library/plan.json --to //server/libs/Components --dry-run"],
+    "librarian": ["ecadlib librarian my_bom.csv -o ws/library",
+                  "ecadlib librarian my_bom.csv --lib ~/kicad/libs -o ws/library --json",
+                  "ecadlib librarian my_bom.csv --offline --sources standard   # no network, no API key"],
+    "datasheet": ["ecadlib datasheet TPS62133.pdf --part TPS62133RGTR -o out/ds",
+                  "ecadlib datasheet estimate ws/library/plan.json"],
+    "release-check": ["ecadlib release-check ws/library/plan.json", "ecadlib release-check ws/library/plan.json --allow CH340C"],
+    "kicad-export": ["ecadlib kicad-export ws/library/plan.json -o ws/kicad --name mylib"],
+    "eagle-export": ["ecadlib eagle-export ws/library/plan.json -o ws/fusion --name mylib",
+                     "ecadlib eagle-export ws/library/plan.json -o ws/fusion --kicad ws/kicad   # convert an existing kicad-export"],
+    "easyeda-export": ["ecadlib easyeda-export ws/library/plan.json -o ws/easyeda --name mylib",
+                       "ecadlib easyeda-export ws/library/plan.json -o ws/easyeda --kicad ws/kicad --json"],
+    "review": ["ecadlib review                                 # every held part in the workspace, one at a time",
+               "ecadlib review ws/library/plan.json --part CH340C", "ecadlib review --workspace ws --yes   # print only, never ask"],
+    "resolve": ["ecadlib resolve ws/library/plan.json list", "ecadlib resolve ws/library/plan.json --part CH340C show"],
+    "upstream": ["ecadlib upstream check-kicad --offline"],
+    "a365": ["ecadlib a365 status ws/library/plan.json --workspace https://acme.365.altium.com"],
+    "queue": ["ecadlib queue list", "ecadlib queue approve 12 --user alice"],
+    "approve": ["ecadlib approve ws/library/plan.json status", "ecadlib approve ws/library/plan.json approve --part CH340C --user alice"],
+    "hub": ["ecadlib hub --workspace ws --lib ~/altium/libs", "ecadlib hub --workspace ws --lack kicad --json",
+            "ecadlib hub --workspace ws --part AO3401A", "ecadlib hub --workspace ws --tool kicad",
+            "ecadlib hub --workspace ws --project boards/sensor/sensor.kicad_pro --copy-to kicad"],
+    "dedupe": ["ecadlib dedupe ws/library/plan.json", "ecadlib dedupe ws/library/plan.json --merge"],
+    "sourcing": ["ecadlib sourcing my_bom.csv --qty 100 --alternates"],
+    "step-gen": ["ecadlib step-gen SOIC-8_3.9x4.9mm_P1.27mm -o out/soic8.step", "ecadlib step-gen --check out/soic8.step"],
+    "upkeep": ["ecadlib upkeep ws/library/plan.json", "ecadlib upkeep ws/library/plan.json --github issue"],
+    "project": ["ecadlib project board.PrjPcb -o bom.csv", "ecadlib project board.PrjPcb --json"],
+    "where-used": ["ecadlib where-used --projects ~/projects --part CH340C"],
+    "sim-models": ["ecadlib sim-models ws/library/plan.json --no-net", "ecadlib sim-models ws/library/plan.json --attach"],
+    "agent-watch": ["ecadlib agent-watch --dry-run", "ecadlib agent-watch --source bom_file:boards/main_bom.csv --json"],
+    "agent": ["ecadlib agent status", "ecadlib agent run --dry-run", "ecadlib agent approve 3 --user alice"],
+    "visual-check": ["ecadlib visual-check out/fp/SOIC-8.kicad_mod --datasheet ds.pdf --pages 3 --render-only"],
+    "symbol": ["ecadlib symbol pins.csv -o out/MCU.SchLib --preview out/MCU.svg"],
+    "setup": ["ecadlib setup", "ecadlib setup --workspace D:/ecadlib --port 8766"],
+    "start": ["ecadlib start", "ecadlib start --setup", "ecadlib start --no-window --no-browser"],
+    "keys": ["ecadlib keys list", "ecadlib keys set ANTHROPIC_API_KEY", "ecadlib keys remove NEXAR_TOKEN"],
+    "doctor": ["ecadlib doctor", "ecadlib doctor --workspace ws --lib ~/kicad/libs --json"],
+    "status": ["ecadlib status", "ecadlib status --workspace ws --json"],
+    "completion": ["ecadlib completion bash > ~/.local/share/bash-completion/completions/ecadlib",
+                   "source <(ecadlib completion zsh)"],
+    "plugins": ["ecadlib plugins list", "ecadlib plugins export myexporter ws/library/plan.json -o out/x"],
+    "notify": ["ecadlib notify show", "ecadlib notify test --event batch_ready"],
+    "kicad-dblib": ["ecadlib kicad-dblib ws/library/plan.json -o ws/kicad --name mylib --export"],
+    "export-parts": ["ecadlib export-parts ws/library/plan.json --format xlsx -o parts.xlsx"],
+    "parity": ["ecadlib parity ws/library/plan.json", "ecadlib parity ws/library/plan.json --kicad ws/kicad --altium ws/altium",
+               "ecadlib parity survey --quick"],
+    "stdparts": ["ecadlib stdparts resolve \"SOIC-8 3.9x4.9mm\"", "ecadlib stdparts coverage my_bom.csv"],
+    "migrate": ["ecadlib migrate ws --check             # exit 1 when files need migrating or are from a newer ecadlib",
+                "ecadlib migrate ws --dry-run", "ecadlib migrate ws                     # backups in .ecadlib_backup/"],
+    "rebuild": ["ecadlib rebuild ws/library --check     # offline; exit 1 on drift",
+                "ecadlib rebuild ws/library --check --keep /tmp/rb --json", "ecadlib rebuild ws/library"],
+}
+
+
+def _fill(parser, fallback=""):
+    if getattr(parser, "_ecadlib_polished", False):
+        return
+    parser._ecadlib_polished = True
+    if not (parser.description or "").strip() and fallback:
+        parser.description = fallback
+    for act in parser._actions:
+        if isinstance(act, argparse._SubParsersAction):
+            helps = {ca.dest: ca.help for ca in act._choices_actions}
+            for name, sub in act.choices.items():
+                _fill(sub, helps.get(name) or "")
+
+
+def polish(parser, cmd, summary=""):
+    """Descriptions everywhere under `parser`, and the examples for `cmd` at the end of its help."""
+    _fill(parser, summary)
+    ex = EXAMPLES.get(cmd)
+    if ex and not getattr(parser, "_ecadlib_examples", False):
+        parser._ecadlib_examples = True
+        orig = parser.format_help
+        text = "\nexamples:\n" + "".join(f"  {e}\n" for e in ex)
+
+        def format_help(self):
+            h = orig()
+            return h if "\nexamples:" in h else h.rstrip("\n") + "\n" + text
+        parser.format_help = types.MethodType(format_help, parser)
+    return parser
+
+
+class installed:
+    """with installed(cmd, summary): the first parser the command parses with gets polish(); restored on exit."""
+    def __init__(self, cmd, summary=""):
+        self.cmd, self.summary, self.done = cmd, summary, False
+
+    def __enter__(self):
+        self.orig = argparse.ArgumentParser.parse_known_args
+        me = self
+
+        def parse_known_args(parser, *a, **k):
+            if not me.done:
+                me.done = True
+                polish(parser, me.cmd, me.summary)
+            return me.orig(parser, *a, **k)
+        argparse.ArgumentParser.parse_known_args = parse_known_args
+        return self
+
+    def __exit__(self, *exc):
+        argparse.ArgumentParser.parse_known_args = self.orig
+        return False

ecadlib/cliutil.py

@@ -0,0 +1,119 @@
+"""Quality-of-life plumbing for the `ecadlib` command line (used by ecadlib/cli.py):
+
+- environment defaults: ECADLIB_LIB (one or more KiCad library folders, separated by the OS path separator, ':' on
+  Linux/macOS, ';' on Windows) and ECADLIB_WORKSPACE (workspace folder) fill in --lib / --workspace for the commands
+  that take them when the flag is not given. A flag on the command line always wins. ECADLIB_CONFIG (the rules file)
+  is handled by ecadlib.rules.find, so every command that searches for ecadlib.toml uses it.
+- friendly errors: an expected error (missing file, bad JSON, bad table, missing package, no permission) becomes one
+  line with a hint instead of a traceback; --debug or ECADLIB_DEBUG=1 shows the traceback."""
+import json, os
+
+# env var -> (flag, {command: None (any) | (subcommands the flag belongs to, added at the end of argv)}).
+# Only commands where the flag means the same thing: --workspace is a folder here (a365 / upkeep / lifecycle /
+# upstream use --workspace for an Altium 365 URL, so they are not listed). `agent` reads ECADLIB_WORKSPACE itself.
+ENV_FLAGS = {
+    "ECADLIB_LIB": ("--lib", {"triage": None, "librarian": None, "resolve": None, "kicad-export": None, "mcp": None,
+                              "ui": None, "agent-watch": None, "agent": ("run", "serve"), "doctor": None}),
+    "ECADLIB_WORKSPACE": ("--workspace", {"mcp": None, "ui": None, "team": None, "queue": None, "agent-watch": None,
+                                          "visual-check": None, "doctor": None, "status": None}),
+}
+DEBUG_ENV = "ECADLIB_DEBUG"
+
+
+def _has_flag(argv, flag):
+    for a in argv:
+        if a == "--":
+            return False
+        if a == flag or a.startswith(flag + "="):
+            return True
+    return False
+
+
+def _subcommand(argv):
+    """The first positional word: the subcommand. Options before it (agent's --workspace / --rules) take a value."""
+    it = iter(argv)
+    for a in it:
+        if a == "--":
+            return None
+        if a.startswith("-"):
+            if "=" not in a:
+                next(it, None)
+            continue
+        return a
+    return None
+
+
+def env_defaults(cmd, argv, environ=None):
+    """argv (the command's own arguments) with --lib / --workspace added from the environment where the command takes
+    them and the user did not give them. Returns (new argv, [notes]) - notes name what was added (for --debug)."""
+    environ = os.environ if environ is None else environ
+    argv, notes = list(argv), []
+    if any(a in ("-h", "--help") for a in argv):
+        return argv, notes
+    for var, (flag, cmds) in ENV_FLAGS.items():
+        val = (environ.get(var) or "").strip()
+        if not val or cmd not in cmds or _has_flag(argv, flag):
+            continue
+        values = [v for v in val.split(os.pathsep) if v.strip()] if flag == "--lib" else [val]
+        extra = [x for v in values for x in (flag, v.strip())]
+        subs = cmds[cmd]
+        if subs is None:
+            argv = extra + argv                       # top-level option: before any subcommand
+        elif _subcommand(argv) in subs:
+            argv = argv + extra                       # a subcommand's option: after it
+        else:
+            continue
+        notes.append(f"{flag} from ${var}")
+    return argv, notes
+
+
+def debug_wanted(argv, environ=None):
+    """(debug?, argv without --debug). --debug may go anywhere before a bare '--'."""
+    environ = os.environ if environ is None else environ
+    out, debug, rest = [], False, False
+    for a in argv:
+        if a == "--":
+            rest = True
+        if a == "--debug" and not rest:
+            debug = True
+            continue
+        out.append(a)
+    return debug or (environ.get(DEBUG_ENV, "").strip().lower() not in ("", "0", "false", "no", "off")), out
+
+
+def friendly(e):
+    """(one-line message, hint, exit code) for an exception, or None when it is not one we expected (a bug)."""
+    name = getattr(e, "filename", None)
+    if isinstance(e, FileNotFoundError):
+        return (f"file not found: {name or e}", f"check the path (relative paths start at {os.getcwd()})", 2)
+    if isinstance(e, PermissionError):
+        return (f"permission denied: {name or e}", "check the file's owner and permissions, or pick another output folder", 2)
+    if isinstance(e, IsADirectoryError):
+        return (f"expected a file but got a folder: {name or e}", "name the file inside that folder", 2)
+    if isinstance(e, NotADirectoryError):
+        return (f"expected a folder but got a file: {name or e}", "check the path", 2)
+    if isinstance(e, json.JSONDecodeError):
+        return (f"not valid JSON: {e.msg} at line {e.lineno} column {e.colno}",
+                "is this the right file? plan.json is written by `ecadlib librarian`", 2)
+    if isinstance(e, UnicodeDecodeError):
+        return (f"file is not readable text ({e.encoding}: {e.reason})", "save the file as UTF-8 (CSV UTF-8 in Excel)", 2)
+    if isinstance(e, ModuleNotFoundError) and e.name and not e.name.startswith("ecadlib"):
+        pkg = {"PIL": "pillow", "yaml": "pyyaml"}.get(e.name.split(".")[0], e.name.split(".")[0])
+        return (f"missing Python package {e.name!r}", f"pip install {pkg}  (or run `ecadlib doctor`)", 2)
+    if type(e).__module__.startswith("pandas") and type(e).__name__ in ("EmptyDataError", "ParserError"):
+        return (f"cannot read the table: {e}", "a BOM needs a header row (CSV, TSV or XLSX)", 2)
+    if isinstance(e, OSError):
+        return (f"{e.strerror or e}" + (f": {name}" if name else ""), "check the path and the disk", 2)
+    return None
+
+
+def report(cmd, e, out):
+    """Print one line (and a hint) for e to `out`; returns the exit code."""
+    f = friendly(e)
+    if f is None:
+        msg, hint, code = (f"internal error ({type(e).__name__}: {e})",
+                           f"run again with --debug (or {DEBUG_ENV}=1) for the traceback, and please report it", 1)
+    else:
+        msg, hint, code = f[0], f[1] + "; --debug shows the traceback", f[2]
+    print(f"ecadlib {cmd}: {msg}\n  hint: {hint}", file=out)
+    return code