Adom Library

@@ -54,23 +54,31 @@ enum Commands {     /// placeholder until the model is brought into a Fusion session.     #[command(name = "bind-3d")]     Bind3d {-        /// Path to the .lbr to patch+        /// Path to the .lbr to patch (omit with --record-only)         #[arg(long)]-        lbr: PathBuf,+        lbr: Option<PathBuf>,         /// Self-hosted model: the versioned file URN-        /// (urn:adsk.wipprod:fs.file:vf.<id>?version=1). The usual case.+        /// (urn:adsk.wipprod:fs.file:vf.<id>?version=N). The usual case.         #[arg(long, conflicts_with = "urn")]         wip_urn: Option<String>,         /// Managed (library.io) part: an urn:adsk.eagle:package:NNN/V URN.         #[arg(long)]         urn: Option<String>,+        /// Optional dm.lineage URN — recorded as sidecar provenance ONLY,+        /// never written into the .lbr (Fusion pins the versioned fs.file URN).+        #[arg(long)]+        lineage_urn: Option<String>,+        /// Record the URN into the sidecar only; don't touch the .lbr. Use after+        /// the bridge attaches the model (in-Fusion library is source of truth).+        #[arg(long)]+        record_only: bool,         /// Package to attach to (default: the .lbr's first/device package)         #[arg(long)]         package: Option<String>,         /// Output path (default: patch --lbr in place)         #[arg(short, long)]         output: Option<PathBuf>,-        /// Also patch this sidecar manifest's binding + status to bound+        /// Sidecar manifest to record the binding + status into         #[arg(long)]         sidecar: Option<PathBuf>,     },@@ -706,37 +714,73 @@ fn write_fusion3d_sidecar(             "units": "mm"         },         "placement": {-            // .kicad_mod footprints are centred on the package origin (0,0),-            // seat plane at Z=0. Identity unless chipfit reports an offset.+            // Orientation hint/override for the bridge's auto-orient (which+            // rotates the smallest bbox dim to Z). .kicad_mod footprints are+            // centred on the package origin (0,0), seat plane Z=0; set a known+            // pin-1 rotation/offset here when a part needs it.             "translation_mm": [0.0, 0.0, 0.0],             "rotation_deg": [0.0, 0.0, 0.0],-            "note": "Footprint origin is the package centre; pin 1 per the .lbr <smd>. Run chipfit to confirm pin-1 alignment / seat Z before the FINISH step."+            "note": "Orientation hint/override. Footprint origin is the package centre; pin 1 per the .lbr <smd>. Run chipfit to confirm pin-1 alignment / seat Z before the FINISH step."         },-        // How the bridge should link the model once it's in Fusion. Self-hosted-        // is the normal path; managed is only for library.io parts.+        // How the model is linked once the bridge has attached it. Self-hosted+        // is the normal path; managed is only for library.io parts. adom-lbr+        // OWNS this record (the in-Fusion library is the runtime source of+        // truth); it's filled in by `bind-3d` once the bridge reports the URN.         "binding": {             "scheme": "self-hosted",+            // The versioned file URN that goes in the .lbr. Recorded after the+            // attach (the bridge reports it via fusion_aps_file_info+            // {query:"<package>"} after Save). Always fs.file:vf …?version=N.             "wip_urn": serde_json::Value::Null,+            // Optional provenance only — the stable cross-version id for+            // re-resolving the latest version. NEVER written into the .lbr.+            "lineage_urn": serde_json::Value::Null,             "package3d_attrs": {                 "urn": "",-                "wip_urn": "<urn:adsk.wipprod:fs.file:vf.<id>?version=1>",+                "wip_urn": "<urn:adsk.wipprod:fs.file:vf.<id>?version=N>",                 "locally_modified": "yes",                 "type": "model"             },-            "note": "Self-uploaded model → wip_urn (versioned fs.file:vf, ?version=1) with urn=\"\" empty. urn:adsk.eagle:package is MANAGED-only. A bare wip_urn does NOT auto-render on a cold open — the model still has to be brought into a session via the generator FINISH."+            "note": "Self-uploaded model → wip_urn = versioned fs.file:vf …?version=N (urn=\"\" empty). NEVER dm.lineage in the .lbr (keep lineage as sidecar provenance only). urn:adsk.eagle:package is MANAGED-only. A bare wip_urn does NOT auto-render on a cold open — the model must be brought into a session via the FINISH."         },         "status": "pending-fusion-attach",         "bridge_steps": [             "Open the .lbr in Fusion (library ACTIVE) — the 2D symbol + footprint are already valid.",-            format!("Electron.Create3DPackage for package '{package}' → import model.path → auto-orient → Package3DStop (FINISH) → Save. This BOTH binds the package and renders the model."),+            format!("Electron.Create3DPackage for package '{package}' → import model.path → auto-orient (placement overrides if set) → Package3DStop (FINISH) → Save. This BOTH binds the package and renders the model."),             "The sidecar needs no pre-minted URN; the FINISH step is what makes the body appear.",-            format!("(Optional fast-path, only if the model is already cloud-synced) `adom-lbr bind-3d --lbr <lbr> --wip-urn <urn:adsk.wipprod:fs.file:vf.<id>?version=1>` pre-writes the binding for package '{package}'. Note: a pre-written wip_urn alone shows a gray placeholder until the model is brought into a session."),+            format!("After Save, report the URN: fusion_aps_file_info {{query:\"{package}\"}} returns the tip fs.file:vf.<id>?version=N. Record it: `adom-lbr bind-3d --record-only --sidecar <this.json> --wip-urn <that-urn>` (writes binding.wip_urn + status=bound; pass --lineage-urn for optional provenance)."),+            "(Optional fast-path) once recorded/known-synced, `adom-lbr bind-3d --lbr <lbr> --wip-urn <…fs.file:vf…?version=N>` pre-writes the binding into the .lbr. NB a pre-written wip_urn shows a gray placeholder until the model is brought into a session.",             "Verify the 3D body seats on the footprint with pin 1 aligned."         ]     });     fs::write(side_path, serde_json::to_string_pretty(&manifest).unwrap() + "\n") } +/// Record a 3D binding into the `*.fusion3d.json` sidecar: the versioned URN+/// (`binding.wip_urn` for self-hosted, `binding.urn` for managed), an optional+/// `dm.lineage` provenance URN, and `status: "bound"`. adom-lbr owns this record;+/// the in-Fusion library is the runtime source of truth.+fn update_sidecar_binding(side: &std::path::Path, link: &str, managed: bool, lineage: Option<&str>) {+    match fs::read_to_string(side).ok().and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok()) {+        Some(mut v) => {+            if managed {+                v["binding"]["urn"] = serde_json::Value::String(link.to_string());+                v["binding"]["scheme"] = serde_json::Value::String("managed".into());+            } else {+                v["binding"]["wip_urn"] = serde_json::Value::String(link.to_string());+                v["binding"]["scheme"] = serde_json::Value::String("self-hosted".into());+            }+            if let Some(l) = lineage {+                v["binding"]["lineage_urn"] = serde_json::Value::String(l.to_string());+            }+            v["status"] = serde_json::Value::String("bound".into());+            let _ = fs::write(side, serde_json::to_string_pretty(&v).unwrap() + "\n");+            println!("OK: Recorded binding in sidecar {} (status -> bound)", side.display());+        }+        None => eprintln!("WARN: Could not update sidecar {}", side.display()),+    }+}+ /// Patch a 3D-model binding into a `.lbr`, making the reference self-contained. /// Adds (or replaces) the `<packages3d>` section after `</packages>` and inserts /// a `<package3dinstance>` into the device(s) using `package` (defaults to the@@ -1218,7 +1262,7 @@ fn main() {             }         } -        Commands::Bind3d { lbr, wip_urn, urn, package, output, sidecar } => {+        Commands::Bind3d { lbr, wip_urn, urn, lineage_urn, record_only, package, output, sidecar } => {             // Exactly one of --wip-urn (self-hosted) or --urn (managed).             let (link, managed) = match (wip_urn.as_deref(), urn.as_deref()) {                 (Some(w), None) => (w.to_string(), false),@@ -1232,6 +1276,27 @@ fn main() {                     process::exit(1);                 }             };+            // A dm.lineage URN must never land in the .lbr — Fusion pins the+            // versioned fs.file URN. Route lineage to provenance instead.+            if link.contains("dm.lineage") {+                eprintln!("ERROR: that's a dm.lineage URN — it must not go in the .lbr. Pass the versioned fs.file:vf…?version=N URN to --wip-urn, and the lineage URN to --lineage-urn (sidecar provenance only).");+                process::exit(1);+            }++            // Record-only: update the sidecar provenance, leave the .lbr alone.+            if record_only {+                let Some(side) = sidecar.as_ref() else {+                    eprintln!("ERROR: --record-only needs --sidecar <manifest.json> to write into.");+                    process::exit(1);+                };+                update_sidecar_binding(side, &link, managed, lineage_urn.as_deref());+                return;+            }++            let Some(lbr) = lbr else {+                eprintln!("ERROR: bind-3d needs --lbr <file.lbr> (or --record-only to update just the sidecar).");+                process::exit(1);+            };             let content = fs::read_to_string(&lbr).unwrap_or_else(|e| {                 eprintln!("ERROR: Cannot read {}: {}", lbr.display(), e);                 process::exit(1);@@ -1258,21 +1323,7 @@ fn main() {             }              if let Some(side) = &sidecar {-                match fs::read_to_string(side).ok().and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok()) {-                    Some(mut v) => {-                        if managed {-                            v["binding"]["urn"] = serde_json::Value::String(link.clone());-                            v["binding"]["scheme"] = serde_json::Value::String("managed".into());-                        } else {-                            v["binding"]["wip_urn"] = serde_json::Value::String(link.clone());-                            v["binding"]["scheme"] = serde_json::Value::String("self-hosted".into());-                        }-                        v["status"] = serde_json::Value::String("bound".into());-                        let _ = fs::write(side, serde_json::to_string_pretty(&v).unwrap() + "\n");-                        println!("OK: Updated sidecar {} (status -> bound)", side.display());-                    }-                    None => eprintln!("WARN: Could not update sidecar {}", side.display()),-                }+                update_sidecar_binding(side, &link, managed, lineage_urn.as_deref());             }              if !lint.passed {