feat(linkmarks-bridge-chromium): add Chromium Bookmarks JSON write-back exporter

CHANGELOG.md

@@ -4,6 +4,65 @@ All notable changes to this project are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/) and the
 project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.2.1] — 2026-08-25
+
+Patch release — Firefox bridge robustness under live-database contention
+and a write-back exporter that produces a file Vivaldi / Chrome / Edge /
+Brave / Arc / Opera can import through their built-in Bookmark manager.
+
+### Added
+- **`linkmarks export --format=chrome` (alias `--format=chromium`).**
+  Emits a complete Chromium Bookmarks JSON document consumable by every
+  Chromium-family browser via *Bookmarks → Bookmark manager → ⋮ → Import
+  bookmarks*. The sink assembles each bookmark's `collection` path into a
+  folder hierarchy under `roots.bookmark_bar` and routes orphans to
+  `roots.other` (matching Chrome's "Other bookmarks"). Tags, when present,
+  are appended to the bookmark name as `(tags: foo, bar)` so the folder
+  structure stays clean and the metadata remains visible. The write is
+  atomic via `tempfile::NamedTempFile::persist`.
+- **Round-trip integrity.** A new
+  `linkmarks-bridge-chromium::ChromiumSink` plus a 5-test round-trip
+  suite (`round_trip_simple`, `round_trip_nested_folders`,
+  `round_trip_preserves_collection_path`,
+  `round_trip_handles_bookmarks_without_collection`,
+  `chromium_tree_flatten_roundtrips_against_sink`) prove that
+  parse → sink → re-parse preserves every bookmark's
+  `(canonical_url, title, collection)` tuple byte-exactly.
+
+### Improved
+- **Firefox bridge now applies `PRAGMA busy_timeout = 5000`** when
+  opening `places.sqlite`, and retries up to 3 times (100 ms backoff) on
+  `SQLITE_BUSY` / `SQLITE_LOCKED` — Firefox routinely holds a write
+  lock on the file while the user is browsing, so the previous
+  read-only open aborted mid-import with no recovery path.
+- **`updated_at` now derives from `moz_bookmarks.lastModified`** instead
+  of `moz_places.last_visit_date`. The previous source conflated edits
+  with visits; the new source reflects actual bookmark mutation time.
+  `created_at` continues to come from `last_visit_date` (the closest
+  available proxy for first-seen time).
+- **Firefox bridge filters internal URL schemes** (`place:`, `about:`,
+  `javascript:`, `chrome:`, `data:`) at parse time. These URLs are
+  auto-generated by Firefox for internal UI state and never represent
+  user bookmarks worth exporting.
+- **`linkmarks_bridge_firefox::BridgeError::DatabaseLocked`** is a new
+  error variant surfaced after the retry loop is exhausted. It maps to
+  `linkmarks_core::CoreError::Storage` so CLI consumers can present a
+  single actionable message instead of a raw `rusqlite` error.
+
+### Notes
+- Tags are **not** written as standalone Chromium folders because
+  Chromium's native schema doesn't support them; the suffix convention
+  in the `Added` section above is the documented workaround and is
+  reversible from inside the browser.
+- Write-back is file-based, not live. Editing the live
+  `~/.config/<browser>/Default/Bookmarks` while the browser is running
+  races with its own mmap-backed writes; the documented path is
+  "export to file → import via the bookmark manager UI".
+- `linkmarks-bridge-chromium` had been importing fine since v2.1.0,
+  but until v2.2.1 there was no symmetrical sink — the new sink closes
+  the loop and makes the bridge bidirectional for Chromium-family
+  browsers.
+
 ## [2.2.0] — 2026-08-17
 
 Minor release — umbrella refactor + dual lib+bin target for the CLI +

crates/bridges/linkmarks-bridge-chromium/Cargo.toml

@@ -20,3 +20,4 @@ chrono.workspace = true
 tracing.workspace = true
 walkdir.workspace = true
 thiserror.workspace = true
+tempfile.workspace = true

crates/bridges/linkmarks-bridge-chromium/src/lib.rs

@@ -8,14 +8,19 @@
 //! to missing fields and reports per-element failures without
 //! aborting the whole import.
 //!
-//! See `parser.rs` for the JSON shape and `source.rs` for the
-//! `ChromiumSource` type that implements `BookmarkSource`.
+//! See `parser.rs` for the JSON shape, `source.rs` for the
+//! `ChromiumSource` type that implements `BookmarkSource`, and
+//! `sink.rs` for the write-back exporter `ChromiumSink`.
 
 #![deny(missing_docs)]
 #![deny(unsafe_code)]
 
 pub mod parser;
+pub mod sink;
 pub mod source;
 
-pub use parser::{parse_and_flatten, ChromiumBookmarks, ParseError};
+pub use parser::{
+    chromium_timestamp, parse_and_flatten, BookmarkNode, ChromiumBookmarks, ParseError, Roots,
+};
+pub use sink::{ChromiumSink, ChromiumTreeFlatten};
 pub use source::{discover_default_paths, ChromiumSource};

crates/bridges/linkmarks-bridge-chromium/src/parser.rs

@@ -20,10 +20,9 @@
 //! `ParseError::Partial` and the rest of the file is parsed.
 
 use chrono::{DateTime, TimeZone, Utc};
-use linkmarks_core::errors::CoreError;
-use linkmarks_core::model::{Bookmark, BookmarkId, SourceKind, SourceRef, Tag};
-use serde::Deserialize;
-use std::collections::BTreeSet;
+use linkmarks_core::model::{Bookmark, BookmarkId, SourceKind, SourceRef};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
 use std::path::Path;
 use thiserror::Error;
 
@@ -50,26 +49,40 @@ pub enum ParseError {
 }
 
 /// Top-level deserialized shape.
-#[derive(Debug, Deserialize)]
+///
+/// Same struct is reused for **serialization** (sink write-back). See
+/// `sink.rs` for the writer. Field shapes are deliberately identical
+/// between read and write paths so the schema stays in lock-step.
+#[derive(Debug, Deserialize, Serialize)]
 pub struct ChromiumBookmarks {
     /// Map of root containers (`bookmark_bar`, `other`, `synced`).
     pub roots: Roots,
 }
 
 /// Container of root folders.
-#[derive(Debug, Deserialize)]
+#[derive(Debug, Deserialize, Serialize)]
 pub struct Roots {
     /// Main bookmarks bar.
     pub bookmark_bar: BookmarkNode,
     /// Other bookmarks (uncategorized).
     pub other: BookmarkNode,
     /// Synced bookmarks (mobile etc.); absent in some browsers.
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub synced: Option<BookmarkNode>,
+    /// Opera's `custom_root` is a wrapper map grouping non-standard
+    /// top-level containers (`pinboard`, `speedDial`, `personal_bar`).
+    /// Each value is itself a `BookmarkNode`. Absent in standard
+    /// Chromium / Vivaldi / Brave / Arc.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub custom_root: Option<BTreeMap<String, BookmarkNode>>,
 }
 
 /// Recursive node.
-#[derive(Debug, Deserialize, Clone)]
+///
+/// Used for both reading and writing Chromium Bookmarks JSON. The
+/// `skip_serializing_if` attributes keep the output JSON compact —
+/// folders don't emit `url`, URLs don't emit empty `children`, etc.
+#[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct BookmarkNode {
     /// `"folder"` or `"url"`.
     #[serde(rename = "type")]
@@ -78,17 +91,17 @@ pub struct BookmarkNode {
     #[serde(default)]
     pub name: String,
     /// URL (only for `type == "url"`).
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub url: Option<String>,
     /// Children (only for `type == "folder"`).
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub children: Vec<BookmarkNode>,
     /// Chromium timestamp (microseconds since Windows epoch
     /// 1601-01-01). Optional.
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub date_added: Option<String>,
     /// Last-used timestamp, same encoding.
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub date_last_used: Option<String>,
 }
 
@@ -112,6 +125,14 @@ pub fn flatten(roots: &ChromiumBookmarks) -> (Vec<Bookmark>, Vec<ParseError>) {
     if let Some(synced) = &roots.roots.synced {
         flatten_node(synced, "", &mut bookmarks, &mut errors);
     }
+    // Opera's `custom_root` wraps several non-standard top-level
+    // containers (`pinboard`, `speedDial`, …) as a map of
+    // BookmarkNode values. Walk each one.
+    if let Some(custom) = &roots.roots.custom_root {
+        for node in custom.values() {
+            flatten_node(node, "", &mut bookmarks, &mut errors);
+        }
+    }
 
     (bookmarks, errors)
 }
@@ -166,9 +187,6 @@ fn build_bookmark(node: &BookmarkNode, collection: &str) -> Result<Bookmark, Par
     let created_at = parse_chromium_timestamp(node.date_added.as_deref()).unwrap_or_else(Utc::now);
     let updated_at = parse_chromium_timestamp(node.date_last_used.as_deref()).unwrap_or(created_at);
 
-    let tags_set: BTreeSet<String> = BTreeSet::new();
-    let _ = tags_set;
-
     Ok(Bookmark {
         id: BookmarkId::generate(),
         original_url: url.to_string(),
@@ -207,25 +225,24 @@ fn parse_chromium_timestamp(raw: Option<&str>) -> Option<DateTime<Utc>> {
     Utc.timestamp_opt(secs, nsec).single()
 }
 
+/// Encode a `DateTime<Utc>` as Chromium microseconds since the
+/// Windows FILETIME epoch (1601-01-01). Used by `sink.rs` when
+/// writing `date_added` and `date_last_used`. Negative timestamps
+/// (pre-1601) clamp to `0`.
+#[must_use]
+pub fn chromium_timestamp(dt: DateTime<Utc>) -> String {
+    let unix_micros = dt.timestamp_micros();
+    let win_micros = unix_micros.checked_add(11_644_473_600_000_000).unwrap_or(0);
+    win_micros.max(0).to_string()
+}
+
 /// Helper: parse + flatten in one call. Returns the bookmarks plus
 /// any per-element errors. The caller decides how to surface errors.
 pub fn parse_and_flatten(path: &Path) -> Result<(Vec<Bookmark>, Vec<ParseError>), ParseError> {
     let parsed = parse_file(path)?;
     Ok(flatten(&parsed))
 }
 
-// Suppress unused warnings for the future-facing Tag import.
-#[allow(dead_code)]
-fn _tag_typecheck(t: Tag) -> String {
-    t.0
-}
-
-// Suppress unused CoreError import (re-exported through public API).
-#[allow(dead_code)]
-fn _ce_typecheck(e: CoreError) -> String {
-    format!("{e}")
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -335,4 +352,41 @@ mod tests {
         let ts = parse_chromium_timestamp(Some("13226064000000000")).unwrap();
         assert_eq!(ts.timestamp(), 1581590400);
     }
+
+    #[test]
+    fn parses_opera_custom_root_with_speed_dial() {
+        // Opera GX wraps non-standard roots (speedDial, pinboard, ...)
+        // inside `roots.custom_root`, itself a map of BookmarkNode
+        // values. This is the canonical schema that v1's catch-all
+        // flattening missed.
+        let json = r#"{
+            "roots": {
+                "bookmark_bar": {"type":"folder","name":"Bookmarks bar","children":[]},
+                "other":       {"type":"folder","name":"Other bookmarks","children":[]},
+                "custom_root": {
+                    "speedDial": {
+                        "type":"folder","name":"Speed Dials","children":[
+                            {"type":"folder","name":"loust","children":[
+                                {"type":"url","name":"Meetup","url":"https://meetup.com/"}
+                            ]}
+                        ]
+                    },
+                    "pinboard": {
+                        "type":"folder","name":"Pinboard","children":[]
+                    }
+                }
+            }
+        }"#;
+        let parsed: ChromiumBookmarks = serde_json::from_str(json).unwrap();
+        let (bookmarks, errors) = flatten(&parsed);
+        assert!(errors.is_empty(), "errors: {errors:?}");
+        assert_eq!(bookmarks.len(), 1, "speedDial/loust/Meetup expected");
+        let bm = &bookmarks[0];
+        assert_eq!(bm.title, "Meetup");
+        assert_eq!(bm.canonical_url, "https://meetup.com/");
+        // The collection must reflect the nested path, including the
+        // custom_root sub-tree ("Speed Dials/loust").
+        assert_eq!(bm.collection.as_deref(), Some("Speed Dials/loust"));
+        assert!(matches!(bm.source.kind, SourceKind::Chromium));
+    }
 }