[draft] Provider-based pin system

[derVedro]

Rovr could benefit of a pin system basing of various bookmarks and pins providers. The user could define a specific provider or a list of them via a configuration file:

[interface]  
pins_bookmarks = ["kde", "gtk"]
pins_places = ["empty"]

Currently, reading support for the two major Linux bookmark providers has been implemented: GTK and KDE.

It's a quite simple but extensible system. A new source could be easily added by implementing PinProvider protocol and registering it through a decorator.

---

by submitting this pull request, i agree that

• i have run poe check to check for any style issues and fixed them
• i have tested rovr (and also ran poe test if applicable) to make sure my changes do not break anything
• cache, logs, dotfiles and/or others were not accidentally added to git's tracking history
• my commits (or at least the pr title) follow the conventional commits format as much as possible
• the documentation has been updated wherever necessary (run poe gen-schema and poe gen-keys if applicable)

Summary by Sourcery

Introduce a provider-based pin system configurable via interface settings for places and bookmarks, including support for Rovr, GTK, and KDE sources.

New Features:

• Allow configuring pin places and bookmarks via interface.pins_places and interface.pins_bookmarks provider lists.
• Add pluggable pin providers for Rovr-managed pins, default places, GTK bookmarks, KDE bookmarks, and an empty provider.

Documentation:

• Document the new interface.pins_places and interface.pins_bookmarks configuration options and their allowed provider values in the config schema reference.

[sourcery-ai]

Reviewer's Guide

Introduces a provider-based pin system for Rovr that loads sidebar places and bookmark pins from configurable providers (Rovr JSON, default built-ins, GTK, KDE, or empty), and wires this into the config schema and documentation.

Sequence diagram for loading pins from configurable providers

sequenceDiagram
    actor User
    participant ConfigFile as RovrConfigToml
    participant Config as config_object
    participant App as RovrApp
    participant Pins as pins_module
    participant PlacesProv as places_providers
    participant BookProv as bookmarks_providers

    User->>ConfigFile: Edit interface.pins_places
    User->>ConfigFile: Edit interface.pins_bookmarks
    ConfigFile-->>Config: Parsed interface section

    User->>App: Open sidebar with pins
    App->>Pins: load_pins()

    Pins->>Config: Read interface.pins_places
    loop for each provider in pins_places
        Pins->>PlacesProv: lookup provider in _places_providers
        PlacesProv-->>Pins: provider_class
        Pins->>provider_class: load_pins()
        provider_class-->>Pins: list of PinItem places
    end

    Pins->>Config: Read interface.pins_bookmarks
    loop for each provider in pins_bookmarks
        Pins->>BookProv: lookup provider in _bookmarks_providers
        BookProv-->>Pins: provider_class
        Pins->>provider_class: load_pins()
        provider_class-->>Pins: list of PinItem bookmarks
    end

    Pins-->>App: PinsDict {default, pins}
    App-->>User: Render sidebar pins from providers

Loading

Class diagram for provider-based pin system

classDiagram
    class PinItem {
        +string name
        +string path
    }

    class PinsDict {
        +list~PinItem~ default
        +list~PinItem~ pins
    }

    class PinProvider {
        <<protocol>>
        +load_pins() list~PinItem~
        +add_pin(pin_name string, pin_path string or bytes) void
        +remove_pin(pin_path string or bytes) void
        +toggle_pin(pin_name string, pin_path string) void
    }

    class EmptyPinProvider {
        +load_pins() list~PinItem~
    }

    class DefaultPlaces {
        +load_pins() list~PinItem~
    }

    class RovrPinedPlaces {
        +load_pins() list~PinItem~
    }

    class RovrPinedBookmarks {
        +load_pins() list~PinItem~
    }

    class GTKBookmarks {
        +string bookmarks_path
        +load_pins() list~PinItem~
    }

    class KDEBookmarks {
        +string bookmarks_path
        +load_pins() list~PinItem~
    }

    class pins_module_helpers {
        +_places_providers dict
        +_bookmarks_providers dict
        +_register(name, bucket) function
        +register_places(name) function
        +register_bookmarks(name) function
        +_expand_vars(path string) string
        +_sanitize(pins list~PinItem~) list~PinItem~
        +load_pins() PinsDict
    }

    PinProvider <|.. EmptyPinProvider
    PinProvider <|.. DefaultPlaces
    PinProvider <|.. RovrPinedPlaces
    PinProvider <|.. RovrPinedBookmarks
    PinProvider <|.. GTKBookmarks
    PinProvider <|.. KDEBookmarks

    pins_module_helpers "1" o-- "many" PinProvider
    pins_module_helpers ..> RovrVars
    pins_module_helpers ..> config
    GTKBookmarks ..> Path
    KDEBookmarks ..> Path
    KDEBookmarks ..> ET

Loading

File-Level Changes

Change	Details	Files
Refactor pin loading to provider-based architecture with protocol and registries for places and bookmarks.	Introduce PinProvider protocol defining load_pins/add_pin/remove_pin/toggle_pin contract. Add internal registries and register_places/register_bookmarks decorators to map provider names to provider classes. Replace global JSON-based load_pins implementation with logic that aggregates pins from configured providers for places and bookmarks. Add helper functions to expand RovrVars variables and normalise/sanitise pin paths.	src/rovr/functions/pins.py
Add concrete pin providers for default Rovr pins, stored JSON pins, empty provider, and GTK/KDE bookmarks.	Implement EmptyPinProvider for cases where no pins should be loaded. Implement DefaultPlaces provider returning the previous default set of standard folders, passed through sanitisation. Implement RovrPinedPlaces and RovrPinedBookmarks providers that read existing pins.json (with fallback to defaults for places) and sanitise paths. Implement GTKBookmarks provider that parses ~/.config/gtk-3.0/bookmarks and converts file URIs to paths. Implement KDEBookmarks provider that parses ~/.local/share/kfile/bookmarks.xml and extracts bookmark titles and hrefs as paths.	src/rovr/functions/pins.py
Extend configuration schema and docs to support configurable pin providers for places and bookmarks.	Document new interface.pins_places and interface.pins_bookmarks config options in the schema reference, including defaults and allowed enum values. Update the interface properties table to include pins_places and pins_bookmarks with appropriate descriptions. Extend JSON schema to define pins_places and pins_bookmarks as array-of-enum fields with defaults and allowed provider values (empty/default/rovr/gtk/kde as applicable).	docs/src/content/docs/dev/reference/schema.mdx src/rovr/config/schema.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.