update_pcb_from_schematic

Exports the schematic's netlist, loads the assigned footprints from
libraries, and binds every pad to its net. Creates the .kicad_pcb if
it does not exist; new footprints land in a grid cluster at orientation
0, written as KiCad writes a footprint it has just loaded (no angle on the
footprint, library pad and text angles normalized as KiCad holds them). Existing
footprints are matched by reference and keep their position; a footprint in KiCad
7's form, on the board or from its library, takes the symbol's reference and value
in its (fp_text reference|value ...), and the update is refused when one holds %V or
%R, which KiCad reads there as a variable. A changed
footprint assignment swaps the footprint as KiCad's exchange does
(pcbnew/pcb_edit_frame.cpp:2346-2587 at 9.0.8): it keeps its position,
angle and side, its texts turned with it as the exchange turns them
(SetOrientation, then on a KiCad 10 board KeepUpright on those it pairs
with old ones), and its uuid, its pads' (by number; on a KiCad 10 board
only a number each footprint holds once) and its fields' (by name), so a
group still finds it. Off the quarter turns a swapped footprint reads as
KiCad's exchange leaves it without matching pcbnew's save byte for byte:
footprint-relative coordinates stay as the library writes them where
pcbnew re-derives them through two RotatePoint roundings, an fp_rect stays
where pcbnew writes an fp_poly, and arc mid points stay as written. A
locked footprint is not swapped
(skipped: footprint_locked), nor is one whose new footprint carries what
this tool cannot move or flip (skipped: footprint_unsupported); either
still takes the symbol's value, fields and nets. A new footprint carrying
what this tool cannot move is not added (skipped: footprint_unsupported).
Stale board footprints are reported, and removed only with delete_stale
(a locked one, in any spelling KiCad reads, never is, and neither is one
marked board only: KiCad's update keeps both). Zones are NOT refilled: run
fill_zones afterward. Net names arrive exactly as KiCad's F8 produces them
(local labels sheet-prefixed, e.g. "/SIG"); read them with list_pcb_nets.
A pad whose net did not change is left as it is, and one that gains a net
gets it where KiCad's writer puts it. A net that left the schematic goes to
no net with everything on it, written as the board's format writes no net,
unless a pad of a footprint that stays on the board is still on it (a stale
footprint that is kept: delete_stale off, or locked, or board only); such a
net keeps its row and everything on it. Segments, arcs and vias sent to no
net are counted in orphaned_tracks, zones in orphaned_zones, and copper
shapes are named in warnings. Nothing on a renamed net is moved to its new
name: it goes to no net with the rest, or stays on the old net while a kept
pad holds it.

What KiCad's own update copies from the symbol follows it here, with
two exceptions named below. The Value. Every other symbol field, as hidden
text on the fabrication layer of the footprint's side: Datasheet and
Description are updated where the library footprint put them, a new field
is added at the footprint's origin at the footprint's own angle (mirrored
on the back), and a field that left the symbol stays on the footprint
(KiCad keeps a footprint's library fields the same way, and text the
user may have placed is not an import's to remove). The symbol's
footprint filters, as KiCad's (property ki_fp_filters ...). The DNP and
"In BOM" boxes, set and cleared on the footprint's attributes; on a
KiCad 10 netlist "Exclude from position files" too, while on KiCad 9,
whose netlist has no such marker, that flag stays the board's own, as
the mounting type, board_only and the courtyard choice always do. The
sheet name and file, and the path that links the footprint to its
symbol. A symbol with "On board" unticked is never placed and is listed
in excluded_from_board; a footprint it left behind is reported stale like
any other. Not copied: the Component Class field, which KiCad assigns as
a component class rather than a field (dropped here), and KiCad 10's
variant overrides, which are not applied. Existing footprints whose
fields, filters, flags or sheet linkage moved are listed in
fields_updated; a second run that changes nothing writes nothing.

A footprint's library nickname is resolved the way KiCad resolves it:
the project's own fp-lib-table first (beside the .kicad_pro, or beside
the board or the schematic when none is named), then .pretty directories
beside the board and the schematic, then KICAD_FP_LIB, then the user's
global fp-lib-table together with the libraries the Plugin and Content
Manager installed, then KiCad's stock footprints. ${KIPRJMOD}, the
variables of Preferences > Configure Paths (kicad_common.json), the
${KICAD*_3RD_PARTY} and ${KICAD*_FOOTPRINT_DIR} families and the other
KiCad path variables expand as KiCad expands them: the environment
first, then the configured value, then KiCad's own default. A nickname
none of those know is reported in skipped as footprint_lib_not_found.
place_footprint resolves through the same code, so a hand-placed part
and an imported one resolve to the same file.

Requires kicad-cli. It no longer needs KiCad's pcbnew Python bindings.

Every byte this writes goes through the server's byte-preserving write, so
a board's format stamp does not move and the parts of it this tool did not
touch arrive unchanged.

Args:
    schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
    pcb_path: Path to .kicad_pcb file (created if missing).
        Optional; omit to use the configured default.
    delete_stale: Remove unlocked board footprints absent from the schematic, except
        those marked board only
    project_path: Path to .kicad_pro for explicit root resolution (sub-sheets)