KiCad - the KiCad Bridge

@@ -1,4 +1,4 @@-# The EDA Bridge Standard's verb names (adom/eda-bridge-standard verbs/standard.json, reference altium 0.2.88). Generated by tools/sync_standard_names.py; do not edit.+# The EDA Bridge Standard's verb names (adom/eda-bridge-standard verbs/standard.json, reference altium 0.2.89). Generated by tools/sync_standard_names.py; do not edit. a365_configure a365_files_upload a365_library_overview@@ -24,6 +24,18 @@ animate_view annotate apply_pours apply_silkscreen+aps_browse+aps_create_folder+aps_download+aps_file_info+aps_open+aps_recent+aps_search+aps_set_client_id+aps_signin+aps_status+aps_upload+aps_versions assembly_check auto_classes autoroute@@ -38,9 +50,11 @@ build_board build_footprint build_schematic build_symbol_modes+cancel_run check_clearance check_dialogs check_orientation+cleanup_cloud_files cleanup_libs clone_symbol close@@ -56,12 +70,14 @@ copper_balance copper_layers copy_footprint copy_routing+create_cloud_folder create_footprint create_part_project create_symbol cross_check cross_probe current_capacity+delete_cloud_file demo describe diagnostics@@ -73,6 +89,7 @@ document_info edit_footprint edit_parts edit_pours+edit_tracks ensure_licensed estimate_cost eval@@ -91,6 +108,7 @@ export_pos export_spice export_step extension_ping+extensions extract_intlib fab_check find_space@@ -122,12 +140,20 @@ library_views license license_status lint_library+list_cloud_files+list_cloud_projects list_commands list_designators list_installed_libraries list_library list_nets log_tail+managed_library_create+managed_library_link+managed_library_pull+managed_library_push+managed_library_unlink+model_check move_parts net_classes net_connections@@ -141,16 +167,19 @@ panel panelize part_parameters pcb_report+physical_properties pin_pad_check place_decoupling place_on_pcb place_on_sch+place_parts place_vias placement_check plan_fanout plan_route plate_vias pour_state+preferences prewarm progress project_create@@ -206,7 +235,9 @@ sch_fix_connectivity sch_hierarchy sch_items sch_junction+sch_label sch_move_region+sch_no_connect sch_page sch_pins sch_place_part@@ -218,9 +249,11 @@ sch_swap_part sch_text sch_trace_point sch_update_from_library+sch_wire sch_zoom schematic_data schematic_review+select_items select_net selection selftest_script_error

@@ -224,6 +224,46 @@ pub static VERBS: &[Verb] = &[         related: &["kicad_set_models", "kicad_set_params", "kicad_sym_info"],         pitfalls: &["Footprint filters are name patterns KiCad offers, not implementations a part switches between as in Altium."],     },+    Verb {+        name: "kicad_place_parts",+        summary: "Put footprints from a library onto a board, each with its position, rotation and side (the standard's place_parts), and read them back.",+        mechanism: Mechanism::File, risk: "write", timeout_sec: 300,+        input: "{\"filePath\": \"C:/.../x.kicad_pcb\", \"parts\": [{\"library\": \"Resistor_SMD\", \"footprint\": \"R_0603_1608Metric\", \"ref\"?: \"R12\" | \"R\", \"value\"?: \"10k\", \"x\": 120, \"y\": 95, \"rotation\"?: 0, \"side\"?: \"top|bottom\", \"nets\"?: {\"1\": \"GND\"}}], \"frame\"?: \"standard\", \"dryRun\"?: false, \"validate\"?: true, \"expectedRevision\"?}",+        example: "kicad_place_parts {\"filePath\":\"C:/p/b.kicad_pcb\",\"parts\":[{\"library\":\"Resistor_SMD\",\"footprint\":\"R_0603_1608Metric\",\"ref\":\"R12\",\"x\":120,\"y\":95}]}",+        hint: "results has ok or err:... per part, in order, and placed reads each one back from KiCad. One call to kicad_add_footprint per part. On a board with a schematic, parts normally arrive through kicad_update_pcb: a part placed here is on no sheet.",+        related: &["kicad_add_footprint", "kicad_update_pcb_from_schematic", "kicad_move_footprint", "kicad_routing_state"],+        pitfalls: &["On an open board each part is its own Undo step: KiCad's API takes them one at a time here.", "A failing part does not undo the ones before it; results says which landed."],+    },+    Verb {+        name: "kicad_edit_tracks",+        summary: "Change given tracks by their routing_state id: width, layer and ends (the standard's edit_tracks). One Undo step, read back.",+        mechanism: Mechanism::File, risk: "write", timeout_sec: 180,+        input: "{\"filePath\": \"C:/.../x.kicad_pcb\", \"tracks\": [{\"id\": \"<uuid>\", \"width\"?: 0.3, \"layer\"?: \"B.Cu\", \"start\"?: [x, y], \"end\"?: [x, y]}], \"dryRun\"?: false, \"expectedRevision\"?}",+        example: "kicad_edit_tracks {\"filePath\":\"C:/p/b.kicad_pcb\",\"tracks\":[{\"id\":\"<uuid>\",\"width\":0.5}]}",+        hint: "The ids are in kicad_routing_state: tracks[].id with model:\"standard\", segments[].uuid without. changes shows before and after, verified says each was read back, and results has ok per track. KiCad's DRC checks the change first and refuses new errors (drc_rejected, nothing changed).",+        related: &["kicad_modify_track", "kicad_routing_state", "kicad_set_track_width", "kicad_remove_items"],+        pitfalls: &["The board must be open in the PCB editor.", "Changing a track's layer does not add the vias its ends now need."],+    },+    Verb {+        name: "kicad_extensions",+        summary: "KiCad's plugins and add-ons through its Plugin and Content Manager (the standard's extensions): list what is installed, install one, remove one.",+        mechanism: Mechanism::File, risk: "write", timeout_sec: 300,+        input: "{\"action\"?: \"list|install|remove\", \"id\"?: \"com.vendor.plugin\", \"source\"?: \"https://.../repository.json\" | \"C:/.../package.zip\", \"version\"?: \"1.1.0\", \"checkUpdates\"?: true}",+        example: "kicad_extensions {\"action\":\"list\"}",+        hint: "extensions [{id, name, version, kind, updateAvailable, latestVersion}]. install takes a repository URL with id, or a local package zip; remove takes id. KiCad loads plugins when it starts, so restart it after a change.",+        related: &["kicad_pcm_list", "kicad_pcm_install", "kicad_pcm_uninstall", "kicad_pcm_search"],+        pitfalls: &["Not install_extension: KiCad needs no helper of the bridge's inside it."],+    },+    Verb {+        name: "kicad_preferences",+        summary: "Read KiCad's own settings, all or one by dotted path, or change them with set (the standard's preferences). KiCad rewrites its settings on exit, so set is refused while it runs.",+        mechanism: Mechanism::File, risk: "write", timeout_sec: 30,+        input: "{\"key\"?: \"pcbnew.editing.track_width_increment\" (<file>.<path>, default every file), \"set\"?: {\"kicad_common.appearance.show_scrollbars\": true}}",+        example: "kicad_preferences {\"key\":\"kicad_common.appearance\"}",+        hint: "The first part of a key names a JSON file in KiCad's settings folder (kicad, kicad_common, pcbnew, eeschema...), and the rest is the path inside it. current has what you asked for; applied has {ok, requested} per key. set makes a .bak of each file it changes and writes only existing files. With KiCad running, set answers tool_running with reason:\"tool_running\".",+        related: &["kicad_readiness", "kicad_ipc_api", "kicad_set_settings"],+        pitfalls: &["Keys come from KiCad's own files and change between versions: read first.", "kicad_settings is another job: the bridge's own settings."],+    }, ];  pub fn dispatch(state: &mut State, command: &str, args: &Value) -> Option<Value> {@@ -244,6 +284,10 @@ pub fn dispatch(state: &mut State, command: &str, args: &Value) -> Option<Value>         "kicad_schematic_data" => sheet_read(state, args, true),         "kicad_pcb_report" => pcb_report(state, args),         "kicad_instances" => instances(state),+        "kicad_place_parts" => place_parts(state, args),+        "kicad_edit_tracks" => edit_tracks(state, args),+        "kicad_extensions" => extensions(state, args),+        "kicad_preferences" => preferences(state, args),         "kicad_ensure_licensed" => ensure_licensed(state),         "kicad_signin_status" => signin_status(state),         "kicad_setup_trial" => setup_trial(state),@@ -806,6 +850,218 @@ fn pcb_report(state: &mut State, args: &Value) -> Value {     out } +fn place_parts(state: &mut State, args: &Value) -> Value {+    let Some(parts) = args.get("parts").and_then(Value::as_array).filter(|p| !p.is_empty()) else {+        return fail("missing_arg", "parts is required", "[{library, footprint, ref?, value?, x, y, rotation?, side?, nets?}]");+    };+    let mut rev = args.get("expectedRevision").cloned();+    let dry = args.get("dryRun") == Some(&json!(true));+    let mut q = json!({"model": "standard"});+    if let Some(f) = args.get("filePath") {+        q["filePath"] = f.clone();+    }+    // The standard's expectedRevision is optional and KiCad's live add wants one. The parts already there tell the+    // new ones apart afterwards, including a reference like "R" that KiCad numbers itself.+    let first = crate::verbs::call(state, "kicad_routing_state", &q);+    if rev.is_none() {+        rev = first.get("revision").filter(|r| r.is_string()).cloned();+    }+    let before: Vec<String> = first["components"].as_array().into_iter().flatten().filter_map(|c| c["ref"].as_str().map(str::to_string)).collect();+    let (mut results, mut placed) = (Vec::new(), Vec::new());+    let mut landed = false;+    for p in parts {+        let (lib, fp) = (p["library"].as_str().unwrap_or(""), p["footprint"].as_str().unwrap_or(""));+        let id = if fp.contains(':') || lib.is_empty() { fp.to_string() } else { format!("{lib}:{fp}") };+        if id.is_empty() || !p["x"].is_number() || !p["y"].is_number() {+            results.push(json!("err:needs library, footprint, x and y"));+            continue;+        }+        let side = match p["side"].as_str() { Some("bottom") | Some("B.Cu") => "B.Cu", _ => "F.Cu" };+        let mut a = json!({"libraryId": id, "x": p["x"], "y": p["y"], "side": side, "reference": p["ref"].as_str().unwrap_or("REF"), "dryRun": dry});+        for (k, v) in [("filePath", args.get("filePath")), ("frame", args.get("frame")), ("validate", args.get("validate")), ("rotation", p.get("rotation")), ("value", p.get("value")), ("nets", p.get("nets")), ("expectedRevision", rev.as_ref())] {+            if let Some(v) = v.filter(|v| !v.is_null()) {+                a[k] = v.clone();+            }+        }+        let r = crate::verbs::call(state, "kicad_add_footprint", &a);+        if r["success"] == json!(true) {+            results.push(json!("ok"));+            if let Some(n) = r.get("revision").filter(|n| n.is_string()) {+                rev = Some(n.clone());+            }+            landed = true;+        } else {+            results.push(json!(format!("err:{}", r["error"].as_str().unwrap_or("not placed"))));+        }+    }+    if !dry && landed {+        let st = crate::verbs::call(state, "kicad_routing_state", &q);+        for c in st["components"].as_array().into_iter().flatten().filter(|c| c["ref"].as_str().is_some_and(|r| !before.iter().any(|n| n == r))) {+            placed.push(json!({"ref": c["ref"], "x": c["x"], "y": c["y"], "rotation": c["rotation"], "side": c["side"]}));+        }+    }+    let ok = results.iter().all(|r| r == "ok");+    let mut out = json!({"success": ok, "results": results, "placed": placed, "mutated": landed && !dry, "dryRun": dry, "revision": rev, "frame": "standard: placed reads y up"});+    if !ok {+        out["errorCode"] = json!("part_failed");+        out["error"] = json!("not every part was placed: results says which");+        out["_hint"] = json!("The parts that landed stay; fix the others and call again with only those.");+    }+    out+}++fn edit_tracks(state: &mut State, args: &Value) -> Value {+    let Some(tracks) = args.get("tracks").and_then(Value::as_array).filter(|t| !t.is_empty()) else {+        return fail("missing_arg", "tracks is required", "[{id, width?, layer?, start?, end?}]; the ids come from kicad_routing_state.");+    };+    let mut a = args.clone();+    a["changes"] = json!(tracks);+    if let Some(o) = a.as_object_mut() {+        o.remove("tracks");+    }+    let mut r = crate::verbs::call(state, "kicad_modify_track", &a);+    if r["success"] == json!(true) {+        r["results"] = json!(tracks.iter().map(|_| json!("ok")).collect::<Vec<_>>());+    }+    r+}++fn extensions(state: &mut State, args: &Value) -> Value {+    let action = arg_str(args, "action").unwrap_or("list");+    match action {+        "list" => {+            let mut a = json!({});+            if let Some(c) = args.get("checkUpdates") {+                a["checkUpdates"] = c.clone();+            }+            let r = crate::verbs::call(state, "kicad_pcm_list", &a);+            if r["success"] != json!(true) {+                return r;+            }+            let rows: Vec<Value> = r["packages"].as_array().into_iter().flatten().map(|p| json!({"id": p["identifier"], "name": p["name"], "version": p["version"], "kind": p["type"], "updateAvailable": p["updateAvailable"], "latestVersion": p["latestVersion"]})).collect();+            json!({"success": true, "count": rows.len(), "extensions": rows})+        }+        "install" => {+            let Some(src) = arg_str(args, "source") else {+                return fail("missing_arg", "source is required to install", "A repository.json URL with id, or a local package .zip.");+            };+            let mut a = if src.to_ascii_lowercase().ends_with(".zip") && !src.contains("://") { json!({"zipPath": src}) } else { json!({"repositoryUrl": src, "identifier": arg_str(args, "id")}) };+            if let Some(v) = args.get("version") {+                a["version"] = v.clone();+            }+            let mut r = crate::verbs::call(state, "kicad_pcm_install", &a);+            if r["success"] == json!(true) {+                r["installed"] = json!({"id": r.get("identifier").cloned().or_else(|| args.get("id").cloned()), "version": r.get("version")});+            }+            r+        }+        "remove" => {+            let Some(id) = arg_str(args, "id") else {+                return fail("missing_arg", "id is required to remove", "kicad_extensions {action:\"list\"} names them.");+            };+            let mut r = crate::verbs::call(state, "kicad_pcm_uninstall", &json!({"identifier": id}));+            if r["success"] == json!(true) {+                r["removed"] = json!(id);+            }+            r+        }+        other => fail("bad_args", format!("no action {other}"), "action is list, install or remove."),+    }+}++/// `dir`'s settings as {file stem: contents}, or just the ones a dotted key reaches.+fn read_preference(dir: &Path, key: Option<&str>) -> Result<Value, String> {+    match key {+        None => {+            let mut all = serde_json::Map::new();+            for e in std::fs::read_dir(dir).map_err(|e| e.to_string())?.flatten() {+                let p = e.path();+                if ext(&p) == "json" {+                    if let (Some(stem), Some(v)) = (p.file_stem().map(|s| s.to_string_lossy().to_string()), std::fs::read_to_string(&p).ok().and_then(|t| serde_json::from_str::<Value>(&t).ok())) {+                        all.insert(stem, v);+                    }+                }+            }+            Ok(Value::Object(all))+        }+        Some(k) => {+            let (file, path) = preference_key(k)?;+            let text = std::fs::read_to_string(dir.join(format!("{file}.json"))).map_err(|_| format!("KiCad has no settings file {file}.json"))?;+            let mut v: Value = serde_json::from_str(&text).map_err(|e| format!("{file}.json: {e}"))?;+            for seg in &path {+                v = v.get(*seg).cloned().ok_or_else(|| format!("{k}: no {seg} there"))?;+            }+            Ok(json!({ k: v }))+        }+    }+}++/// `pcbnew.editing.width` into its file and its path; the file part is a plain name, never a path.+fn preference_key(key: &str) -> Result<(&str, Vec<&str>), String> {+    let mut it = key.split('.');+    let file = it.next().unwrap_or("");+    if file.is_empty() || !file.chars().all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-') {+        return Err(format!("{key}: the first part must name a settings file, such as pcbnew"));+    }+    Ok((file, it.collect()))+}++/// Apply set: each key to an existing file, with a .bak; a key's parents must already exist.+fn write_preferences(dir: &Path, set: &serde_json::Map<String, Value>) -> Value {+    let mut applied = serde_json::Map::new();+    for (k, requested) in set {+        let done = (|| -> Result<(), String> {+            let (file, path) = preference_key(k)?;+            if path.is_empty() {+                return Err("name a setting inside the file".into());+            }+            let p = dir.join(format!("{file}.json"));+            let text = std::fs::read_to_string(&p).map_err(|_| format!("KiCad has no settings file {file}.json"))?;+            let mut root: Value = serde_json::from_str(&text).map_err(|e| e.to_string())?;+            let mut at = &mut root;+            for seg in &path[..path.len() - 1] {+                at = at.get_mut(*seg).ok_or_else(|| format!("no {seg} there"))?;+            }+            let o = at.as_object_mut().ok_or("the parent is not a group of settings")?;+            o.insert(path[path.len() - 1].to_string(), requested.clone());+            std::fs::write(p.with_extension("json.bak"), &text).map_err(|e| e.to_string())?;+            std::fs::write(&p, serde_json::to_string_pretty(&root).map_err(|e| e.to_string())?).map_err(|e| e.to_string())+        })();+        applied.insert(k.clone(), match done {+            Ok(()) => json!({"ok": true, "requested": requested}),+            Err(e) => json!({"ok": false, "requested": requested, "error": e}),+        });+    }+    Value::Object(applied)+}++fn preferences(state: &mut State, args: &Value) -> Value {+    let info = state.kicad_info();+    let Some(dir) = info.primary().and_then(|p| kicad_core::detect::config_dir(&p.version)) else {+        return fail("not_installed", "KiCad's settings folder was not found", "kicad_readiness says whether KiCad is installed; it writes its settings the first time it runs.");+    };+    if let Some(set) = args.get("set").and_then(Value::as_object) {+        if kicad_running() {+            let mut v = fail("tool_running", "KiCad rewrites its settings when it exits, so set is refused while it runs", "kicad_close, then call again.");+            v["reason"] = json!("tool_running");+            return v;+        }+        let applied = write_preferences(&dir, set);+        let keys: Vec<String> = set.keys().cloned().collect();+        let mut current = serde_json::Map::new();+        for k in keys {+            if let Ok(Value::Object(m)) = read_preference(&dir, Some(&k)) {+                current.extend(m);+            }+        }+        return json!({"success": true, "applied": applied, "current": current, "mutated": true});+    }+    match read_preference(&dir, arg_str(args, "key")) {+        Ok(current) => json!({"success": true, "current": current, "folder": norm(&dir)}),+        Err(e) => fail("key_not_found", e, "Call with no key to see every file and setting."),+    }+}+ fn kicad_running() -> bool {     kicad_platform::native().processes(&["kicad.exe", "pcbnew.exe", "eeschema.exe"]).map(|p| !p.is_empty()).unwrap_or(false) }@@ -1152,6 +1408,25 @@ mod tests {         let _ = std::fs::remove_dir_all(&d);     } +    #[test]+    fn preferences_read_by_path_and_write_only_what_exists() {+        let d = std::env::temp_dir().join(format!("kb-prefs-{}", std::process::id()));+        let _ = std::fs::remove_dir_all(&d);+        std::fs::create_dir_all(&d).unwrap();+        std::fs::write(d.join("pcbnew.json"), r#"{"editing":{"width":1,"snap":true}}"#).unwrap();+        assert_eq!(read_preference(&d, Some("pcbnew.editing.width")).unwrap()["pcbnew.editing.width"], 1);+        assert_eq!(read_preference(&d, None).unwrap()["pcbnew"]["editing"]["snap"], true);+        assert!(read_preference(&d, Some("pcbnew.nope")).is_err());+        assert!(read_preference(&d, Some("../secret.x")).is_err(), "a key never leaves the folder");+        let set = json!({"pcbnew.editing.width": 2, "pcbnew.nope.x": 3, "absent.a.b": 4}).as_object().cloned().unwrap();+        let a = write_preferences(&d, &set);+        assert_eq!((a["pcbnew.editing.width"]["ok"].as_bool(), a["pcbnew.nope.x"]["ok"].as_bool(), a["absent.a.b"]["ok"].as_bool()), (Some(true), Some(false), Some(false)), "{a}");+        assert_eq!(read_preference(&d, Some("pcbnew.editing.width")).unwrap()["pcbnew.editing.width"], 2);+        assert!(d.join("pcbnew.json.bak").is_file());+        assert!(!d.join("absent.json").exists());+        let _ = std::fs::remove_dir_all(&d);+    }+     #[test]     fn a_footprint_library_reports_its_numbers() {         let v = footprint_numbers("(footprint \"X\" (fp_line (start 0 0) (end 1 0)) (fp_line (start 0 0) (end 0 1)) (pad \"1\" smd rect (at -1 0) (size 1 2)) (pad \"2\" smd rect (at 1 0) (size 1 2)) (model \"x.step\"))", "X").unwrap();

@@ -170,30 +170,79 @@ pub fn child_spans(text: &str, span: (usize, usize)) -> Vec<(usize, usize)> {     top_level_spans(inner).into_iter().map(|(a, b)| (a + span.0, b + span.0)).collect() } -fn set_property(block: &str, key: &str, value: &str) -> String {-    let head = format!("(property {} ", q(key));-    if let Some(i) = block.find(&head) {-        let start = i + head.len();-        if block[start..].starts_with('"') {-            // the quoted value: find its closing quote, escapes respected-            let mut j = start + 1;-            let b = block.as_bytes();-            while j < b.len() {-                if b[j] == b'\\' {-                    j += 2;-                    continue;-                }-                if b[j] == b'"' {-                    break;-                }-                j += 1;+/// One s-expression token at `i` (quoted, escapes respected, or bare): its end.+fn token_end(block: &str, i: usize) -> usize {+    let b = block.as_bytes();+    if b.get(i) == Some(&b'"') {+        let mut j = i + 1;+        while j < b.len() {+            match b[j] {+                b'\\' => j += 2,+                b'"' => return j + 1,+                _ => j += 1,             }-            let mut out = block.to_string();-            out.replace_range(start..=j.min(block.len() - 1), &q(value));-            return out;         }+        return b.len();     }-    block.to_string()+    let mut j = i;+    while j < b.len() && !b[j].is_ascii_whitespace() && b[j] != b'(' && b[j] != b')' {+        j += 1;+    }+    j+}++fn skip_space(block: &str, mut i: usize) -> usize {+    let b = block.as_bytes();+    while i < b.len() && b[i].is_ascii_whitespace() {+        i += 1;+    }+    i+}++/// Where `open` (a list head such as `(property`) starts a list, however it is spaced: the positions after it.+fn list_heads<'a>(block: &'a str, open: &'a str) -> impl Iterator<Item = (usize, usize)> + 'a {+    block.match_indices(open).filter_map(move |(i, _)| {+        let after = i + open.len();+        block.as_bytes().get(after).filter(|c| c.is_ascii_whitespace()).map(|_| (i, after))+    })+}++/// A footprint's Reference or Value, whichever way its library wrote it (wiki #138: library files spaced or broken+/// over lines differently from KiCad's own, and KiCad 5/6's `fp_text`, kept their REF**). A footprint with neither+/// gets the property. Rewritten as KiCad writes it, because `board_only` and other readers look for that spelling.+fn set_property(block: &str, key: &str, value: &str) -> String {+    let unquote = |t: &str| t.trim_matches('"').to_string();+    for (start, after) in list_heads(block, "(property") {+        let k0 = skip_space(block, after);+        let k1 = token_end(block, k0);+        if unquote(&block[k0..k1]) != key {+            continue;+        }+        let v0 = skip_space(block, k1);+        let v1 = token_end(block, v0);+        let mut out = block.to_string();+        out.replace_range(start..v1, &format!("(property {} {}", q(key), q(value)));+        return out;+    }+    let legacy = key.to_ascii_lowercase();+    for (_, after) in list_heads(block, "(fp_text") {+        let k0 = skip_space(block, after);+        let k1 = token_end(block, k0);+        if block[k0..k1] != legacy {+            continue;+        }+        let v0 = skip_space(block, k1);+        let v1 = token_end(block, v0);+        let mut out = block.to_string();+        out.replace_range(v0..v1, &q(value));+        return out;+    }+    let layer = if key == "Reference" { "F.SilkS" } else { "F.Fab" };+    let prop = format!("(property {} {} (at 0 0 0) (layer {}) (uuid {}) (effects (font (size 1 1) (thickness 0.15))))\n\t\t", q(key), q(value), q(layer), q(&new_uuid()));+    let mut out = block.to_string();+    let at = list_heads(block, "(fp_").chain(list_heads(block, "(pad")).map(|(i, _)| i).min().or_else(|| block.rfind(')')).unwrap_or(block.len());+    out.insert_str(at, &prop);+    out }  fn net_clause(fmt: NetFormat, number: Option<i64>, name: &str) -> String {@@ -245,7 +294,7 @@ fn add_angle(block: &str, rot: f64) -> String {         return block.to_string();     }     let mut out = block.to_string();-    let targets: Vec<(usize, usize)> = child_spans(&out, (0, out.len())).into_iter().filter(|(s, _)| ["(pad ", "(property ", "(fp_text "].iter().any(|h| out[*s..].starts_with(h))).collect();+    let targets: Vec<(usize, usize)> = child_spans(&out, (0, out.len())).into_iter().filter(|(s, _)| ["(pad", "(property", "(fp_text"].iter().any(|h| out[*s..].starts_with(h) && out[*s + h.len()..].starts_with(|c: char| c.is_whitespace()))).collect();     for (s, e) in targets.into_iter().rev() {         let item = out[s..e].to_string();         let Some(at) = child_spans(&item, (0, item.len())).into_iter().find(|(a, _)| item[*a..].starts_with("(at ")) else { continue };@@ -323,6 +372,10 @@ pub fn instantiate(module: &str, lib_id: &str, reference: &str, value: &str, at:     let mut numbers_seen = Vec::new();     let parsed = pcb::parse_pcb_text(&format!("(kicad_pcb\n\t{block}\n)"), "lib").map_err(|e| RoutingError::new("library_unparsable", format!("{lib_id}: {e}")))?;     if let Some(fp) = parsed.footprints.first() {+        // Wiki #138: never hand back a part that still answers to its library's placeholder.+        if fp.reference != reference {+            return Err(RoutingError::new("reference_not_set", format!("{lib_id}: the footprint reads as {:?} after setting its reference to {reference}", fp.reference)));+        }         for p in &fp.pads {             if p.number.is_empty() || numbers_seen.contains(&p.number) {                 continue;@@ -520,6 +573,30 @@ pub fn apply(text: &str, board: &Board, nl: &Netlist, opts: &ApplyOpts, module: mod tests {     use super::*; +    #[test]+    fn a_reference_is_set_however_the_library_spaced_it() {+        // wiki #138: each of these kept REF** and then read as a missing part+        let pad = "(pad \"1\" smd rect (at 0 0) (size 1 1) (layers \"F.Cu\"))";+        for (name, field) in [+            ("KiCad's own", "(property \"Reference\" \"REF**\" (at 0 0 0) (layer \"F.SilkS\"))"),+            ("two spaces", "(property \"Reference\"  \"REF**\" (at 0 0 0) (layer \"F.SilkS\"))"),+            ("value on its own line", "(property \"Reference\"\n\t\t\"REF**\"\n\t\t(at 0 0 0) (layer \"F.SilkS\"))"),+            ("CRLF", "(property \"Reference\"\r\n\t\"REF**\"\r\n\t(at 0 0 0) (layer \"F.SilkS\"))"),+            ("each token on a line", "(property\n\t\t\"Reference\"\n\t\t\"REF**\"\n\t\t(at 0 0 0) (layer \"F.SilkS\"))"),+            ("bare words", "(property Reference REF** (at 0 0 0) (layer \"F.SilkS\"))"),+            ("KiCad 6's fp_text", "(fp_text reference \"REF**\" (at 0 0) (layer \"F.SilkS\"))"),+            ("KiCad 5's fp_text, bare", "(fp_text reference REF** (at 0 0) (layer F.SilkS))"),+            ("no Reference at all", ""),+        ] {+            let module = format!("(footprint \"CR0402-FX-1002GLF\" (layer \"F.Cu\") {field} (property \"Value\" \"X\" (at 0 1 0) (layer \"F.Fab\")) {pad})");+            let b = instantiate(&module, "PCM_lib:CR0402-FX-1002GLF", "R15", "10k", (1.0, 2.0), 0.0, "F.Cu", "u-1", Some("/abc"), &|_| None, NetFormat::Name, &BTreeMap::new()).unwrap_or_else(|e| panic!("{name}: {}", e.message));+            assert!(!b.contains("REF**"), "{name}: {b}");+            let parsed = pcb::parse_pcb_text(&format!("(kicad_pcb\n{b}\n)"), "t").unwrap();+            assert_eq!(parsed.footprints[0].reference, "R15", "{name}: {b}");+            assert_eq!(parsed.footprints[0].value, "10k", "{name}: {b}");+        }+    }+     #[test]     fn an_escaped_board_net_is_the_netlists_plain_name() {         // pic_programmer: the label VPP/MCLR is /VPP{slash}MCLR on the board and /VPP/MCLR in the netlist

@@ -15,6 +15,7 @@ import json import pathlib import subprocess import sys+import tempfile import time  AI_THREAD = "kicad-lane"@@ -140,6 +141,26 @@ def sheet_part(d, base):         nc2 = items("noConnects").get("noConnects") or []         d.check("sch_no_connect", "remove by id takes it away", r, not nc2, nc2) +    # the standard's shape of the same verbs: sheet and id for filePath and uuid, remove on sch_label+    r = d.call("sch_label", {"sheet": sch, "text": "STD1", "at": [57.15, 54.61]})+    n = nets()+    d.check("sch_label", "standard args: the net is STD1", r, any("STD1" in k for k in n), list(n)[:8])+    r = d.call("sch_label", {"sheet": sch, "text": "STD1", "at": [57.15, 54.61], "remove": True})+    n = nets()+    d.check("sch_label", "standard args: remove takes it away", r, not any("STD1" in k for k in n), list(n)[:8])+    r = d.call("sch_no_connect", {"sheet": sch, "at": [76.2, 46.99]})+    nc = items("noConnects").get("noConnects") or []+    if nc:+        r2 = d.call("sch_no_connect", {"sheet": sch, "id": nc[0].get("id"), "remove": True})+        d.check("sch_no_connect", "standard args: a point, then remove by id", r2, len(nc) == 1 and not items("noConnects").get("noConnects"), nc)+    else:+        d.check("sch_no_connect", "standard args: a marker at a point", r, False, nc)+    w0 = len(items("wires").get("wires") or [])+    r = d.call("sch_wire", {"sheet": sch, "points": [[30.48, 25.4], [35.56, 25.4]]})+    d.check("sch_wire", "standard args: one more wire", r, len(items("wires").get("wires") or []) == w0 + 1, w0)+    wid = (items("wires").get("wires") or [{}])[-1].get("id")+    d.call("sch_delete_wire", {"filePath": sch, "from": [30.48, 25.4], "to": [35.56, 25.4]})+     r = d.call("sch_text", {"filePath": sch, "text": "drill note", "at": [30.48, 30.48]})     tx = [t for t in items("texts").get("texts") or [] if t.get("text") == "drill note"]     d.check("sch_text", "the note is there at its point", r, len(tx) == 1 and near(tx[0].get("at"), [30.48, 30.48]), tx)@@ -293,9 +314,52 @@ def file_part(d, base):     l = layers(rf)     d.check("set_layer_count", "the board now has 4 copper layers", r, r.get("countAfter") == 4 and "In1.Cu" in json.dumps(l), {k: l.get(k) for k in ("copper", "copperLayers", "count")}) +    # wiki #138: a library footprint with its reference broken over lines kept REF** and read as missing+    odd = pathlib.Path(tempfile.mkdtemp()) / "R_0603_1608Metric.kicad_mod"+    odd.write_text((ROUTE_FIXTURE / "Fixture.pretty/R_0603_1608Metric.kicad_mod").read_text().replace('(property "Reference" "REF**"', '(property "Reference"\n\t\t"REF**"'))+    d.call("send_files", {"filePaths": [str(odd)], "dest": bdir + "/Fixture.pretty"}, 200)     r = d.call("update_pcb_from_schematic", {"projectPath": bdir + "/route-fixture.kicad_pro", "filePath": bdir + "/route-fixture.kicad_pcb", "netlistPath": bdir + "/route-fixture.net", "execute": True, "allowRemovals": True})     p = d.call("update_pcb_from_schematic", {"filePath": bdir + "/route-fixture.kicad_pcb", "netlistPath": bdir + "/route-fixture.net"})-    d.check("update_pcb_from_schematic", "execute: a second compare says in sync", r, r.get("executed") is True and (p.get("plan") or {}).get("inSync") is True, {"exec": r.get("error"), "after": (p.get("plan") or {}).get("changeCount"), "changes": p.get("changeOrder")})+    d.check("update_pcb_from_schematic", "execute: a second compare says in sync, R2 has its reference", r, r.get("executed") is True and (p.get("plan") or {}).get("inSync") is True and part(bdir + "/route-fixture.kicad_pcb", "R2"), {"exec": r.get("error"), "after": (p.get("plan") or {}).get("changeCount"), "changes": p.get("changeOrder")})+++def cancel_part(d, base):+    print("[cancel] stop a Freerouting job")+    bdir = base + "/cancel"+    d.call("send_files", {"filePaths": [str(LIVE_BOARD)], "dest": bdir}, 200)+    b = bdir + "/esc-g431-unrouted.kicad_pcb"+    rev0 = d.call("routing_state", {"filePath": b, "source": "file", "model": "standard"}).get("revision")+    j = d.call("autoroute", {"filePath": b, "engine": "freerouting", "job": True, "passes": 50}, 120)+    if j.get("errorCode") == "not_installed" or "not installed" in str(j.get("error")):+        print("  SKIP  cancel_run                       Freerouting is not installed here, so a real stop is NOT proven")+        return+    if j.get("success") is not True:+        d.check("autoroute", "a job started", j, False, j.get("error"))+        return+    for _ in range(20):+        p = d.call("autoroute", {"job": j["job"]})+        if "freerouting" in str(p.get("stepLabel")).lower() or p.get("status") != "running":+            break+        time.sleep(3)+    c = d.call("cancel_run", {"runId": j["job"]})+    d.check("cancel_run", "the running job takes the request", c, c.get("cancelRequested") is True and c.get("runId") == j["job"], {k: c.get(k) for k in ("cancelRequested", "stage", "reason")})+    p = {}+    for _ in range(40):+        p = d.call("autoroute", {"job": j["job"]})+        if p.get("status") != "running":+            break+        time.sleep(3)+    rev1 = d.call("routing_state", {"filePath": b, "source": "file", "model": "standard"}).get("revision")+    d.check("cancel_run", "the job ended cancelled, the board unchanged", p, p.get("errorCode") == "cancelled" and rev0 == rev1, {"status": p.get("status"), "code": p.get("errorCode"), "same": rev0 == rev1})+++def prefs_part(d, base):+    print("[prefs] KiCad closed: a setting really changes, then back")+    d.call("close", {"discardChanges": True}, 120)+    key = "kicad_common.adom_drill_marker"+    r = d.call("preferences", {"set": {"kicad_common.adom_drill_marker": 41}})+    g = d.call("preferences", {"key": key})+    d.check("preferences", "set reads back", r, (g.get("current") or {}).get(key) == 41, r.get("applied"))   def live_part(d, base):@@ -404,6 +468,29 @@ def live_part(d, base):     p1 = len([t for t in state().get("tracks") or [] if t.get("net") in (pa, pb)])     d.check("route_diff_pair", "live: both nets got copper", r, p1 >= p0 + 2, [pa, pb, p0, p1, r.get("errorCode"), r.get("error")]) +    g1 = [t for t in state().get("tracks") or [] if t.get("net") == "GND"]+    if g1:+        tid = g1[0].get("id") or g1[0].get("uuid")+        r = d.call("edit_tracks", {"filePath": b, "expectedRevision": rev[0], "validate": False, "tracks": [{"id": tid, "width": 0.33}]})+        g2 = next((t for t in state().get("tracks") or [] if (t.get("id") or t.get("uuid")) == tid), {})+        d.check("edit_tracks", "live: the track is 0.33 wide", r, abs((g2.get("width") or 0) - 0.33) < 0.001, [g2.get("width"), r.get("errorCode"), r.get("error")])+    r = d.call("place_parts", {"filePath": b, "expectedRevision": rev[0], "parts": [{"library": "Resistor_SMD", "footprint": "R_0603_1608Metric", "ref": "R900", "x": 130, "y": 60, "rotation": 90}, {"library": "Resistor_SMD", "footprint": "R_0603_1608Metric", "ref": "R901", "x": 134, "y": 60, "side": "bottom"}], "validate": False}, 300)+    a0, a1 = comp("R900"), comp("R901")+    d.check("place_parts", "live: both parts landed, position, rotation and side", r, near([a0.get("x"), a0.get("y")], [130, -60], 0.01) and abs((a0.get("rotation") or 0) - 90) < 0.01 and a1.get("side") == "bottom", [a0.get("x"), a0.get("y"), a0.get("rotation"), a1.get("side"), r.get("results")])+    r = d.call("place_parts", {"filePath": b, "parts": [{"library": "Resistor_SMD", "footprint": "R_0603_1608Metric", "ref": "TP", "x": 138, "y": 60}], "validate": False}, 300)+    got = (r.get("placed") or [{}])[0]+    d.check("place_parts", "live: a reference KiCad numbers itself reads back", r, str(got.get("ref")).startswith("TP") and near([got.get("x"), got.get("y")], [138, -60], 0.01), r.get("placed"))+    r = d.call("select_items", {"filePath": b, "refs": ["R900", "NOPE9"]})+    g = d.call("get_selection", {"filePath": b})+    d.check("select_items", "live: R900 selected, NOPE9 named as failed", r, "R900" in (g.get("references") or []) and (r.get("failed") or [{}])[0].get("ref") == "NOPE9" and r.get("verified") is False, [g.get("references"), r.get("failed"), r.get("verified")])+    r = d.call("select_items", {"filePath": b, "clear": True})+    g = d.call("get_selection", {"filePath": b})+    d.check("select_items", "live: clear empties the selection", r, not g.get("references"), g.get("references"))+    r = d.call("select_items", {"filePath": b, "where": "sheet", "refs": ["R1"]})+    d.check("select_items", "where:sheet is refused by name", r, r.get("errorCode") == "not_supported", r.get("errorCode"))+    r = d.call("model_check", {"filePath": b})+    d.check("model_check", "per part: found and geometry", r, r.get("checked", 0) > 3 and all("found" in m and "hasGeometry" in m for q in r.get("parts") or [] for m in q.get("models") or []) and any(q.get("models") for q in r.get("parts") or []), {"checked": r.get("checked"), "ok": r.get("ok"), "error": r.get("error")})+    state()     r = edit("ripup_nets", nets=["GND"], dryRun=False)     t2 = [t for t in state().get("tracks") or [] if t.get("net") == "GND"]     d.check("ripup_nets", "live: GND has no tracks left", r, not t2 and len(g1) > 0, [len(g1), len(t2), r.get("errorCode"), r.get("error")])@@ -426,7 +513,7 @@ def live_part(d, base): def main():     ap = argparse.ArgumentParser()     ap.add_argument("--target", required=True)-    ap.add_argument("--part", default="sheet,library,file,live")+    ap.add_argument("--part", default="sheet,library,file,cancel,live")     ap.add_argument("--out")     a = ap.parse_args()     d = Drill(a.target)@@ -441,7 +528,7 @@ def main():         print("FATAL: could not learn the Windows user from kicad_readiness")         return 2     base = f"C:/Users/{user}/Documents/adom-kicad-drill/{time.strftime('%m%d%H%M%S')}"-    parts = {"sheet": sheet_part, "library": library_part, "file": file_part, "live": live_part}+    parts = {"sheet": sheet_part, "library": library_part, "file": file_part, "live": live_part, "cancel": cancel_part, "prefs": prefs_part}     for name in a.part.split(","):         parts[name.strip()](d, base)     fails = [r for r in d.results if not r["pass"]]