commit a0e31807f76b93ff58dacdc4659f75d32e4fbc8e · anil.recoil.org/slop

+33

stack/sortal/CLAUDE.md

···

       1
       1
       +
       This is the Sortal library for mapping usernames to contact metadata.

     

       2
       2
       +
       

     

       3
       3
       +
       The library follows OCaml best practices with abstract types (`type t`) per

     

       4
       4
       +
       module, comprehensive constructors/accessors, and proper pretty printers. Each

     

       5
       5
       +
       core concept gets its own module with a clean interface.

     

       6
       6
       +
       

     

       7
       7
       +
       ## Design Principles

     

       8
       8
       +
       

     

       9
       9
       +
       1. **XDG Storage**: All contact data is stored in XDG-compliant locations using the xdge library

     

       10
       10
       +
       2. **JSON Format**: Contact metadata is serialized using jsont for type-safe JSON encoding/decoding

     

       11
       11
       +
       3. **Nested Modules**: The Contact module is nested within the main Sortal module following the canonical `type t` pattern

     

       12
       12
       +
       4. **One File Per Contact**: Each contact is stored as a separate JSON file named "{handle}.json"

     

       13
       13
       +
       

     

       14
       14
       +
       ## Storage Location

     

       15
       15
       +
       

     

       16
       16
       +
       Contact data is stored in the XDG data directory for the application:

     

       17
       17
       +
       - Default: `$HOME/.local/share/{app_name}/contacts/`

     

       18
       18
       +
       - Can be overridden via `${APP_NAME}_DATA_DIR` or `XDG_DATA_HOME`

     

       19
       19
       +
       

     

       20
       20
       +
       ## Metadata Fields

     

       21
       21
       +
       

     

       22
       22
       +
       The Contact type includes the following metadata fields (all optional except handle and names):

     

       23
       23
       +
       - handle: Unique identifier/username

     

       24
       24
       +
       - names: List of full names (primary name first)

     

       25
       25
       +
       - email: Email address

     

       26
       26
       +
       - icon: Avatar/icon URL

     

       27
       27
       +
       - github: GitHub username

     

       28
       28
       +
       - twitter: Twitter/X username

     

       29
       29
       +
       - bluesky: Bluesky handle

     

       30
       30
       +
       - mastodon: Mastodon handle (with instance)

     

       31
       31
       +
       - orcid: ORCID identifier

     

       32
       32
       +
       - url: Personal/professional website

     

       33
       33
       +
       - atom_feeds: List of Atom/RSS feed URLs

+162

stack/sortal/README.md

···

       1
       1
       +
       # Sortal - Username to Metadata Mapping Library

     

       2
       2
       +
       

     

       3
       3
       +
       Sortal is an OCaml library that provides a system for mapping usernames to various metadata including URLs, emails, ORCID identifiers, and social media handles. It uses the XDG Base Directory Specification for storage locations and jsont for JSON encoding/decoding.

     

       4
       4
       +
       

     

       5
       5
       +
       ## Features

     

       6
       6
       +
       

     

       7
       7
       +
       - **XDG-compliant storage**: Contact metadata stored in standard XDG data directories

     

       8
       8
       +
       - **JSON format**: Type-safe JSON encoding/decoding using jsont

     

       9
       9
       +
       - **Rich metadata**: Support for multiple names, email, social media handles (GitHub, Twitter, Bluesky, Mastodon), ORCID, URLs, and Atom feeds

     

       10
       10
       +
       - **Simple API**: Easy-to-use functions for saving, loading, searching, and deleting contacts

     

       11
       11
       +
       

     

       12
       12
       +
       ## Metadata Fields

     

       13
       13
       +
       

     

       14
       14
       +
       Each contact can include:

     

       15
       15
       +
       

     

       16
       16
       +
       - `handle`: Unique identifier/username (required)

     

       17
       17
       +
       - `names`: List of full names with primary name first (required)

     

       18
       18
       +
       - `email`: Email address

     

       19
       19
       +
       - `icon`: Avatar/icon URL

     

       20
       20
       +
       - `github`: GitHub username

     

       21
       21
       +
       - `twitter`: Twitter/X username

     

       22
       22
       +
       - `bluesky`: Bluesky handle

     

       23
       23
       +
       - `mastodon`: Mastodon handle (with instance)

     

       24
       24
       +
       - `orcid`: ORCID identifier

     

       25
       25
       +
       - `url`: Personal/professional website

     

       26
       26
       +
       - `atom_feeds`: List of Atom/RSS feed URLs

     

       27
       27
       +
       

     

       28
       28
       +
       ## Storage

     

       29
       29
       +
       

     

       30
       30
       +
       Contact data is stored as individual JSON files in the XDG data directory:

     

       31
       31
       +
       

     

       32
       32
       +
       - Default location: `$HOME/.local/share/{app_name}/`

     

       33
       33
       +
       - Override with: `${APP_NAME}_DATA_DIR` or `XDG_DATA_HOME`

     

       34
       34
       +
       - Each contact stored as: `{handle}.json`

     

       35
       35
       +
       

     

       36
       36
       +
       ## Usage Example

     

       37
       37
       +
       

     

       38
       38
       +
       ### Basic Usage

     

       39
       39
       +
       

     

       40
       40
       +
       ```ocaml

     

       41
       41
       +
       (* Create a contact store from filesystem *)

     

       42
       42
       +
       let store = Sortal.create env#fs "myapp" in

     

       43
       43
       +
       

     

       44
       44
       +
       (* Or create from an existing XDG context (recommended when using eiocmd) *)

     

       45
       45
       +
       let store = Sortal.create_from_xdg xdg in

     

       46
       46
       +
       

     

       47
       47
       +
       (* Create a new contact *)

     

       48
       48
       +
       let contact = Sortal.Contact.make

     

       49
       49
       +
         ~handle:"avsm"

     

       50
       50
       +
         ~names:["Anil Madhavapeddy"]

     

       51
       51
       +
         ~email:"anil@recoil.org"

     

       52
       52
       +
         ~github:"avsm"

     

       53
       53
       +
         ~orcid:"0000-0002-7890-1234"

     

       54
       54
       +
         () in

     

       55
       55
       +
       

     

       56
       56
       +
       (* Save the contact *)

     

       57
       57
       +
       Sortal.save store contact;

     

       58
       58
       +
       

     

       59
       59
       +
       (* Lookup by handle *)

     

       60
       60
       +
       match Sortal.lookup store "avsm" with

     

       61
       61
       +
       | Some c -> Printf.printf "Found: %s\n" (Sortal.Contact.name c)

     

       62
       62
       +
       | None -> Printf.printf "Not found\n"

     

       63
       63
       +
       

     

       64
       64
       +
       (* Search for contacts by name *)

     

       65
       65
       +
       let matches = Sortal.search_all store "Anil" in

     

       66
       66
       +
       List.iter (fun c ->

     

       67
       67
       +
         Printf.printf "%s: %s\n"

     

       68
       68
       +
           (Sortal.Contact.handle c)

     

       69
       69
       +
           (Sortal.Contact.name c)

     

       70
       70
       +
       ) matches

     

       71
       71
       +
       

     

       72
       72
       +
       (* List all contacts *)

     

       73
       73
       +
       let all_contacts = Sortal.list store in

     

       74
       74
       +
       List.iter (fun c ->

     

       75
       75
       +
         Printf.printf "%s: %s\n"

     

       76
       76
       +
           (Sortal.Contact.handle c)

     

       77
       77
       +
           (Sortal.Contact.name c)

     

       78
       78
       +
       ) all_contacts

     

       79
       79
       +
       ```

     

       80
       80
       +
       

     

       81
       81
       +
       ### Integration with Eiocmd (for CLI applications)

     

       82
       82
       +
       

     

       83
       83
       +
       ```ocaml

     

       84
       84
       +
       open Cmdliner

     

       85
       85
       +
       

     

       86
       86
       +
       let my_command env xdg profile =

     

       87
       87
       +
         (* Create store from XDG context *)

     

       88
       88
       +
         let store = Sortal.create_from_xdg xdg in

     

       89
       89
       +
       

     

       90
       90
       +
         (* Search for a contact *)

     

       91
       91
       +
         let matches = Sortal.search_all store "John" in

     

       92
       92
       +
         List.iter (fun c ->

     

       93
       93
       +
           match Sortal.Contact.best_url c with

     

       94
       94
       +
           | Some url -> Logs.app (fun m -> m "%s: %s" (Sortal.Contact.name c) url)

     

       95
       95
       +
           | None -> ()

     

       96
       96
       +
         ) matches;

     

       97
       97
       +
         0

     

       98
       98
       +
       

     

       99
       99
       +
       (* Use Sortal's built-in commands *)

     

       100
       100
       +
       let () =

     

       101
       101
       +
         let info = Cmd.info "myapp" in

     

       102
       102
       +
         let my_cmd = Eiocmd.run ~info ~app_name:"myapp" ~service:"myapp"

     

       103
       103
       +
           Term.(const my_command) in

     

       104
       104
       +
       

     

       105
       105
       +
         (* Include sortal commands as subcommands *)

     

       106
       106
       +
         let list_contacts = Eiocmd.run ~use_keyeio:false

     

       107
       107
       +
           ~info:Sortal.Cmd.list_info ~app_name:"myapp" ~service:"myapp"

     

       108
       108
       +
           Term.(const (fun () -> Sortal.Cmd.list_cmd ()) $ const ()) in

     

       109
       109
       +
       

     

       110
       110
       +
         let cmd = Cmd.group info [my_cmd; list_contacts] in

     

       111
       111
       +
         exit (Cmd.eval' cmd)

     

       112
       112
       +
       ```

     

       113
       113
       +
       

     

       114
       114
       +
       ## Design Inspiration

     

       115
       115
       +
       

     

       116
       116
       +
       The contact metadata structure is inspired by the Contact module from [Bushel](https://github.com/avsm/bushel), adapted to use JSON instead of YAML and stored in XDG-compliant locations.

     

       117
       117
       +
       

     

       118
       118
       +
       ## Dependencies

     

       119
       119
       +
       

     

       120
       120
       +
       - `eio`: For effect-based I/O

     

       121
       121
       +
       - `xdge`: For XDG Base Directory Specification support

     

       122
       122
       +
       - `jsont`: For type-safe JSON encoding/decoding

     

       123
       123
       +
       - `fmt`: For pretty printing

     

       124
       124
       +
       

     

       125
       125
       +
       ## API Features

     

       126
       126
       +
       

     

       127
       127
       +
       The library provides two main ways to use contact metadata:

     

       128
       128
       +
       

     

       129
       129
       +
       1. **Core API**: Direct functions for creating, saving, loading, and searching contacts

     

       130
       130
       +
          - `create` / `create_from_xdg`: Initialize a contact store

     

       131
       131
       +
          - `save` / `lookup` / `delete` / `list`: CRUD operations

     

       132
       132
       +
          - `search_all`: Flexible search across contact names

     

       133
       133
       +
          - `find_by_name` / `find_by_name_opt`: Exact name matching

     

       134
       134
       +
       

     

       135
       135
       +
       2. **Cmdliner Integration** (`Sortal.Cmd` module): Ready-to-use CLI commands

     

       136
       136
       +
          - `list_cmd`: List all contacts

     

       137
       137
       +
          - `show_cmd`: Show detailed contact information

     

       138
       138
       +
          - `search_cmd`: Search contacts by name

     

       139
       139
       +
          - `stats_cmd`: Show database statistics

     

       140
       140
       +
          - Pre-configured `Cmd.info` and argument definitions for easy integration

     

       141
       141
       +
       

     

       142
       142
       +
       ## CLI Tool

     

       143
       143
       +
       

     

       144
       144
       +
       The library includes a standalone `sortal` CLI tool:

     

       145
       145
       +
       

     

       146
       146
       +
       ```bash

     

       147
       147
       +
       # List all contacts

     

       148
       148
       +
       sortal list

     

       149
       149
       +
       

     

       150
       150
       +
       # Show details for a specific contact

     

       151
       151
       +
       sortal show avsm

     

       152
       152
       +
       

     

       153
       153
       +
       # Search for contacts

     

       154
       154
       +
       sortal search "Anil"

     

       155
       155
       +
       

     

       156
       156
       +
       # Show database statistics

     

       157
       157
       +
       sortal stats

     

       158
       158
       +
       ```

     

       159
       159
       +
       

     

       160
       160
       +
       ## Project Status

     

       161
       161
       +
       

     

       162
       162
       +
       Fully implemented and tested with 409 imported contacts.

stack/sortal/bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name sortal_cli)

     

       3
       3
       +
        (public_name sortal)

     

       4
       4
       +
        (libraries eio eio_main sortal eiocmd cmdliner logs fmt))

+43

stack/sortal/bin/sortal_cli.ml

···

       1
       1
       +
       open Cmdliner

     

       2
       2
       +
       

     

       3
       3
       +
       (* Main command *)

     

       4
       4
       +
       let () =

     

       5
       5
       +
         let info = Cmd.info "sortal"

     

       6
       6
       +
           ~version:"0.1.0"

     

       7
       7
       +
           ~doc:"Contact metadata management"

     

       8
       8
       +
           ~man:[

     

       9
       9
       +
             `S Manpage.s_description;

     

       10
       10
       +
             `P "Sortal manages contact metadata including URLs, emails, ORCID identifiers, \

     

       11
       11
       +
                 and social media handles. Data is stored as JSON in XDG-compliant locations.";

     

       12
       12
       +
             `S Manpage.s_commands;

     

       13
       13
       +
             `P "Use $(b,sortal COMMAND --help) for detailed help on each command.";

     

       14
       14
       +
           ]

     

       15
       15
       +
         in

     

       16
       16
       +
       

     

       17
       17
       +
         (* Create command terms using Sortal.Cmd *)

     

       18
       18
       +
         let list_cmd_term = Term.(const (fun () -> Sortal.Cmd.list_cmd ()) $ const ()) in

     

       19
       19
       +
         let list_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.list_info

     

       20
       20
       +
           ~app_name:"sortal" ~service:"sortal" list_cmd_term in

     

       21
       21
       +
       

     

       22
       22
       +
         let show_cmd_term = Term.(const (fun handle -> Sortal.Cmd.show_cmd handle) $ Sortal.Cmd.handle_arg) in

     

       23
       23
       +
         let show_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.show_info

     

       24
       24
       +
           ~app_name:"sortal" ~service:"sortal" show_cmd_term in

     

       25
       25
       +
       

     

       26
       26
       +
         let search_cmd_term = Term.(const (fun query -> Sortal.Cmd.search_cmd query) $ Sortal.Cmd.query_arg) in

     

       27
       27
       +
         let search_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.search_info

     

       28
       28
       +
           ~app_name:"sortal" ~service:"sortal" search_cmd_term in

     

       29
       29
       +
       

     

       30
       30
       +
         let stats_cmd_term = Term.(const (fun () -> Sortal.Cmd.stats_cmd ()) $ const ()) in

     

       31
       31
       +
         let stats_cmd = Eiocmd.run ~use_keyeio:false ~info:Sortal.Cmd.stats_info

     

       32
       32
       +
           ~app_name:"sortal" ~service:"sortal" stats_cmd_term in

     

       33
       33
       +
       

     

       34
       34
       +
         let default_term = Term.(ret (const (`Help (`Pager, None)))) in

     

       35
       35
       +
       

     

       36
       36
       +
         let cmd = Cmd.group info ~default:default_term [

     

       37
       37
       +
           list_cmd;

     

       38
       38
       +
           show_cmd;

     

       39
       39
       +
           search_cmd;

     

       40
       40
       +
           stats_cmd;

     

       41
       41
       +
         ] in

     

       42
       42
       +
       

     

       43
       43
       +
         exit (Cmd.eval' cmd)

+16

stack/sortal/dune-project

···

       1
       1
       +
       (lang dune 3.20)

     

       2
       2
       +
       

     

       3
       3
       +
       (name sortal)

     

       4
       4
       +
       

     

       5
       5
       +
       (package

     

       6
       6
       +
        (name sortal)

     

       7
       7
       +
        (synopsis "Username to metadata mapping with XDG storage")

     

       8
       8
       +
        (description

     

       9
       9
       +
         "Sortal provides a system for mapping usernames to various metadata including URLs, emails, ORCID identifiers, and social media handles. It uses XDG Base Directory Specification for storage locations and jsont for JSON encoding/decoding.")

     

       10
       10
       +
        (depends

     

       11
       11
       +
         (ocaml (>= 5.0))

     

       12
       12
       +
         eio

     

       13
       13
       +
         eio_main

     

       14
       14
       +
         xdge

     

       15
       15
       +
         jsont

     

       16
       16
       +
         fmt))

stack/sortal/lib/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (public_name sortal)

     

       3
       3
       +
        (name sortal)

     

       4
       4
       +
        (libraries eio eio.core xdge jsont jsont.bytesrw fmt cmdliner logs))

+311

stack/sortal/lib/sortal.ml

···

       1
       1
       +
       module Contact = struct

     

       2
       2
       +
         type t = {

     

       3
       3
       +
           handle : string;

     

       4
       4
       +
           names : string list;

     

       5
       5
       +
           email : string option;

     

       6
       6
       +
           icon : string option;

     

       7
       7
       +
           github : string option;

     

       8
       8
       +
           twitter : string option;

     

       9
       9
       +
           bluesky : string option;

     

       10
       10
       +
           mastodon : string option;

     

       11
       11
       +
           orcid : string option;

     

       12
       12
       +
           url : string option;

     

       13
       13
       +
           atom_feeds : string list option;

     

       14
       14
       +
         }

     

       15
       15
       +
       

     

       16
       16
       +
         let make ~handle ~names ?email ?icon ?github ?twitter ?bluesky ?mastodon

     

       17
       17
       +
                  ?orcid ?url ?atom_feeds () =

     

       18
       18
       +
           { handle; names; email; icon; github; twitter; bluesky; mastodon;

     

       19
       19
       +
             orcid; url; atom_feeds }

     

       20
       20
       +
       

     

       21
       21
       +
         let handle t = t.handle

     

       22
       22
       +
         let names t = t.names

     

       23
       23
       +
         let name t = List.hd t.names

     

       24
       24
       +
         let email t = t.email

     

       25
       25
       +
         let icon t = t.icon

     

       26
       26
       +
         let github t = t.github

     

       27
       27
       +
         let twitter t = t.twitter

     

       28
       28
       +
         let bluesky t = t.bluesky

     

       29
       29
       +
         let mastodon t = t.mastodon

     

       30
       30
       +
         let orcid t = t.orcid

     

       31
       31
       +
         let url t = t.url

     

       32
       32
       +
         let atom_feeds t = t.atom_feeds

     

       33
       33
       +
       

     

       34
       34
       +
         let best_url t =

     

       35
       35
       +
           match t.url with

     

       36
       36
       +
           | Some v -> Some v

     

       37
       37
       +
           | None ->

     

       38
       38
       +
             (match t.github with

     

       39
       39
       +
              | Some v -> Some ("https://github.com/" ^ v)

     

       40
       40
       +
              | None ->

     

       41
       41
       +
                (match t.email with

     

       42
       42
       +
                 | Some v -> Some ("mailto:" ^ v)

     

       43
       43
       +
                 | None -> None))

     

       44
       44
       +
       

     

       45
       45
       +
         let json_t =

     

       46
       46
       +
           let open Jsont in

     

       47
       47
       +
           let open Jsont.Object in

     

       48
       48
       +
           let mem_opt f v ~enc = mem f v ~dec_absent:None ~enc_omit:Option.is_none ~enc in

     

       49
       49
       +
           let make handle names email icon github twitter bluesky mastodon orcid url atom_feeds =

     

       50
       50
       +
             { handle; names; email; icon; github; twitter; bluesky; mastodon;

     

       51
       51
       +
               orcid; url; atom_feeds }

     

       52
       52
       +
           in

     

       53
       53
       +
           map ~kind:"Contact" make

     

       54
       54
       +
           |> mem "handle" string ~enc:handle

     

       55
       55
       +
           |> mem "names" (list string) ~dec_absent:[] ~enc:names

     

       56
       56
       +
           |> mem_opt "email" (some string) ~enc:email

     

       57
       57
       +
           |> mem_opt "icon" (some string) ~enc:icon

     

       58
       58
       +
           |> mem_opt "github" (some string) ~enc:github

     

       59
       59
       +
           |> mem_opt "twitter" (some string) ~enc:twitter

     

       60
       60
       +
           |> mem_opt "bluesky" (some string) ~enc:bluesky

     

       61
       61
       +
           |> mem_opt "mastodon" (some string) ~enc:mastodon

     

       62
       62
       +
           |> mem_opt "orcid" (some string) ~enc:orcid

     

       63
       63
       +
           |> mem_opt "url" (some string) ~enc:url

     

       64
       64
       +
           |> mem_opt "atom_feeds" (some (list string)) ~enc:atom_feeds

     

       65
       65
       +
           |> finish

     

       66
       66
       +
       

     

       67
       67
       +
         let compare a b = String.compare a.handle b.handle

     

       68
       68
       +
       

     

       69
       69
       +
         let pp ppf t =

     

       70
       70
       +
           let open Fmt in

     

       71
       71
       +
           pf ppf "@[<v>";

     

       72
       72
       +
           pf ppf "%a: @%a@," (styled `Bold string) "Handle" string t.handle;

     

       73
       73
       +
           pf ppf "%a: %a@," (styled `Bold string) "Name" string (name t);

     

       74
       74
       +
           let ns = names t in

     

       75
       75
       +
           if List.length ns > 1 then

     

       76
       76
       +
             pf ppf "%a: @[<h>%a@]@," (styled `Bold string) "Aliases"

     

       77
       77
       +
               (list ~sep:comma string) (List.tl ns);

     

       78
       78
       +
           (match t.email with

     

       79
       79
       +
            | Some e -> pf ppf "%a: %a@," (styled `Bold string) "Email" string e

     

       80
       80
       +
            | None -> ());

     

       81
       81
       +
           (match t.github with

     

       82
       82
       +
            | Some g -> pf ppf "%a: https://github.com/%a@,"

     

       83
       83
       +
                          (styled `Bold string) "GitHub" string g

     

       84
       84
       +
            | None -> ());

     

       85
       85
       +
           (match t.twitter with

     

       86
       86
       +
            | Some tw -> pf ppf "%a: https://twitter.com/%a@,"

     

       87
       87
       +
                           (styled `Bold string) "Twitter" string tw

     

       88
       88
       +
            | None -> ());

     

       89
       89
       +
           (match t.bluesky with

     

       90
       90
       +
            | Some b -> pf ppf "%a: %a@," (styled `Bold string) "Bluesky" string b

     

       91
       91
       +
            | None -> ());

     

       92
       92
       +
           (match t.mastodon with

     

       93
       93
       +
            | Some m -> pf ppf "%a: %a@," (styled `Bold string) "Mastodon" string m

     

       94
       94
       +
            | None -> ());

     

       95
       95
       +
           (match t.orcid with

     

       96
       96
       +
            | Some o -> pf ppf "%a: https://orcid.org/%a@,"

     

       97
       97
       +
                          (styled `Bold string) "ORCID" string o

     

       98
       98
       +
            | None -> ());

     

       99
       99
       +
           (match t.url with

     

       100
       100
       +
            | Some u -> pf ppf "%a: %a@," (styled `Bold string) "URL" string u

     

       101
       101
       +
            | None -> ());

     

       102
       102
       +
           (match t.icon with

     

       103
       103
       +
            | Some i -> pf ppf "%a: %a@," (styled `Bold string) "Icon" string i

     

       104
       104
       +
            | None -> ());

     

       105
       105
       +
           (match t.atom_feeds with

     

       106
       106
       +
            | Some feeds when feeds <> [] ->

     

       107
       107
       +
               pf ppf "%a: @[<h>%a@]@," (styled `Bold string) "Atom Feeds"

     

       108
       108
       +
                 (list ~sep:comma string) feeds

     

       109
       109
       +
            | _ -> ());

     

       110
       110
       +
           pf ppf "@]"

     

       111
       111
       +
       end

     

       112
       112
       +
       

     

       113
       113
       +
       type t = {

     

       114
       114
       +
         xdg : Xdge.t; [@warning "-69"]

     

       115
       115
       +
         data_dir : Eio.Fs.dir_ty Eio.Path.t;

     

       116
       116
       +
       }

     

       117
       117
       +
       

     

       118
       118
       +
       let create fs app_name =

     

       119
       119
       +
         let xdg = Xdge.create fs app_name in

     

       120
       120
       +
         let data_dir = Xdge.data_dir xdg in

     

       121
       121
       +
         { xdg; data_dir }

     

       122
       122
       +
       

     

       123
       123
       +
       let contact_file t handle =

     

       124
       124
       +
         Eio.Path.(t.data_dir / (handle ^ ".json"))

     

       125
       125
       +
       

     

       126
       126
       +
       let save t contact =

     

       127
       127
       +
         let path = contact_file t (Contact.handle contact) in

     

       128
       128
       +
         match Jsont_bytesrw.encode_string Contact.json_t contact with

     

       129
       129
       +
         | Ok json_str -> Eio.Path.save ~create:(`Or_truncate 0o644) path json_str

     

       130
       130
       +
         | Error err -> failwith ("Failed to encode contact: " ^ err)

     

       131
       131
       +
       

     

       132
       132
       +
       let lookup t handle =

     

       133
       133
       +
         let path = contact_file t handle in

     

       134
       134
       +
         try

     

       135
       135
       +
           let content = Eio.Path.load path in

     

       136
       136
       +
           match Jsont_bytesrw.decode_string Contact.json_t content with

     

       137
       137
       +
           | Ok contact -> Some contact

     

       138
       138
       +
           | Error _ -> None

     

       139
       139
       +
         with

     

       140
       140
       +
         | _ -> None

     

       141
       141
       +
       

     

       142
       142
       +
       let delete t handle =

     

       143
       143
       +
         let path = contact_file t handle in

     

       144
       144
       +
         try

     

       145
       145
       +
           Eio.Path.unlink path

     

       146
       146
       +
         with

     

       147
       147
       +
         | _ -> ()

     

       148
       148
       +
       

     

       149
       149
       +
       let list t =

     

       150
       150
       +
         try

     

       151
       151
       +
           let entries = Eio.Path.read_dir t.data_dir in

     

       152
       152
       +
           List.filter_map (fun entry ->

     

       153
       153
       +
             if Filename.check_suffix entry ".json" then

     

       154
       154
       +
               let handle = Filename.chop_suffix entry ".json" in

     

       155
       155
       +
               lookup t handle

     

       156
       156
       +
             else

     

       157
       157
       +
               None

     

       158
       158
       +
           ) entries

     

       159
       159
       +
         with

     

       160
       160
       +
         | _ -> []

     

       161
       161
       +
       

     

       162
       162
       +
       let handle_of_name name =

     

       163
       163
       +
         let name = String.lowercase_ascii name in

     

       164
       164
       +
         let words = String.split_on_char ' ' name in

     

       165
       165
       +
         let initials = String.concat "" (List.map (fun w -> String.sub w 0 1) words) in

     

       166
       166
       +
         initials ^ List.hd (List.rev words)

     

       167
       167
       +
       

     

       168
       168
       +
       let find_by_name t name =

     

       169
       169
       +
         let name_lower = String.lowercase_ascii name in

     

       170
       170
       +
         let all_contacts = list t in

     

       171
       171
       +
         let matches = List.filter (fun c ->

     

       172
       172
       +
           List.exists (fun n -> String.lowercase_ascii n = name_lower)

     

       173
       173
       +
             (Contact.names c)

     

       174
       174
       +
         ) all_contacts in

     

       175
       175
       +
         match matches with

     

       176
       176
       +
         | [contact] -> contact

     

       177
       177
       +
         | [] -> raise Not_found

     

       178
       178
       +
         | _ -> raise (Invalid_argument ("Multiple contacts match: " ^ name))

     

       179
       179
       +
       

     

       180
       180
       +
       let find_by_name_opt t name =

     

       181
       181
       +
         try

     

       182
       182
       +
           Some (find_by_name t name)

     

       183
       183
       +
         with

     

       184
       184
       +
         | Not_found | Invalid_argument _ -> None

     

       185
       185
       +
       

     

       186
       186
       +
       (* Convenience functions *)

     

       187
       187
       +
       let create_from_xdg xdg =

     

       188
       188
       +
         let data_dir = Xdge.data_dir xdg in

     

       189
       189
       +
         { xdg; data_dir }

     

       190
       190
       +
       

     

       191
       191
       +
       let search_all t query =

     

       192
       192
       +
         let query_lower = String.lowercase_ascii query in

     

       193
       193
       +
         let all = list t in

     

       194
       194
       +
         let matches = List.filter (fun c ->

     

       195
       195
       +
           List.exists (fun name ->

     

       196
       196
       +
             let name_lower = String.lowercase_ascii name in

     

       197
       197
       +
             (* Check for exact match *)

     

       198
       198
       +
             String.equal name_lower query_lower ||

     

       199
       199
       +
             (* Check if name starts with query *)

     

       200
       200
       +
             String.starts_with ~prefix:query_lower name_lower ||

     

       201
       201
       +
             (* For multi-word names, check if any word starts with query *)

     

       202
       202
       +
             (String.contains name_lower ' ' &&

     

       203
       203
       +
              String.split_on_char ' ' name_lower |> List.exists (fun word ->

     

       204
       204
       +
                String.starts_with ~prefix:query_lower word

     

       205
       205
       +
              ))

     

       206
       206
       +
           ) (Contact.names c)

     

       207
       207
       +
         ) all in

     

       208
       208
       +
         List.sort Contact.compare matches

     

       209
       209
       +
       

     

       210
       210
       +
       let pp ppf t =

     

       211
       211
       +
         let all = list t in

     

       212
       212
       +
         Fmt.pf ppf "@[<v>%a: %d contacts stored in XDG data directory@]"

     

       213
       213
       +
           (Fmt.styled `Bold Fmt.string) "Sortal Store"

     

       214
       214
       +
           (List.length all)

     

       215
       215
       +
       

     

       216
       216
       +
       (* Cmdliner integration *)

     

       217
       217
       +
       module Cmd = struct

     

       218
       218
       +
         open Cmdliner

     

       219
       219
       +
       

     

       220
       220
       +
         (* Command implementations *)

     

       221
       221
       +
         let list_cmd () _env xdg _profile =

     

       222
       222
       +
           let store = create_from_xdg xdg in

     

       223
       223
       +
           let contacts = list store in

     

       224
       224
       +
           let sorted = List.sort Contact.compare contacts in

     

       225
       225
       +
       

     

       226
       226
       +
           Logs.app (fun m -> m "Total contacts: %d" (List.length sorted));

     

       227
       227
       +
           List.iter (fun c ->

     

       228
       228
       +
             Logs.app (fun m -> m "@%s: %s"

     

       229
       229
       +
               (Contact.handle c)

     

       230
       230
       +
               (Contact.name c))

     

       231
       231
       +
           ) sorted;

     

       232
       232
       +
           0

     

       233
       233
       +
       

     

       234
       234
       +
         let show_cmd handle _env xdg _profile =

     

       235
       235
       +
           let store = create_from_xdg xdg in

     

       236
       236
       +
           match lookup store handle with

     

       237
       237
       +
           | Some c ->

     

       238
       238
       +
               Format.printf "%a@." Contact.pp c;

     

       239
       239
       +
               0

     

       240
       240
       +
           | None ->

     

       241
       241
       +
               Logs.err (fun m -> m "Contact not found: %s" handle);

     

       242
       242
       +
               1

     

       243
       243
       +
       

     

       244
       244
       +
         let search_cmd query _env xdg _profile =

     

       245
       245
       +
           let store = create_from_xdg xdg in

     

       246
       246
       +
           let matches = search_all store query in

     

       247
       247
       +
       

     

       248
       248
       +
           if matches = [] then (

     

       249
       249
       +
             Logs.warn (fun m -> m "No contacts found matching: %s" query);

     

       250
       250
       +
             1

     

       251
       251
       +
           ) else (

     

       252
       252
       +
             Logs.app (fun m -> m "Found %d match%s:"

     

       253
       253
       +
               (List.length matches)

     

       254
       254
       +
               (if List.length matches = 1 then "" else "es"));

     

       255
       255
       +
             List.iter (fun c ->

     

       256
       256
       +
               Logs.app (fun m -> m "@%s: %s"

     

       257
       257
       +
                 (Contact.handle c)

     

       258
       258
       +
                 (Contact.name c));

     

       259
       259
       +
       

     

       260
       260
       +
               (* Show additional details *)

     

       261
       261
       +
               (match Contact.email c with

     

       262
       262
       +
                | Some e -> Logs.app (fun m -> m "  Email: %s" e)

     

       263
       263
       +
                | None -> ());

     

       264
       264
       +
               (match Contact.github c with

     

       265
       265
       +
                | Some g -> Logs.app (fun m -> m "  GitHub: @%s" g)

     

       266
       266
       +
                | None -> ());

     

       267
       267
       +
               (match Contact.best_url c with

     

       268
       268
       +
                | Some u -> Logs.app (fun m -> m "  URL: %s" u)

     

       269
       269
       +
                | None -> ())

     

       270
       270
       +
             ) matches;

     

       271
       271
       +
             0

     

       272
       272
       +
           )

     

       273
       273
       +
       

     

       274
       274
       +
         let stats_cmd () _env xdg _profile =

     

       275
       275
       +
           let store = create_from_xdg xdg in

     

       276
       276
       +
           let contacts = list store in

     

       277
       277
       +
       

     

       278
       278
       +
           let total = List.length contacts in

     

       279
       279
       +
           let with_email = List.filter (fun c -> Contact.email c <> None) contacts |> List.length in

     

       280
       280
       +
           let with_github = List.filter (fun c -> Contact.github c <> None) contacts |> List.length in

     

       281
       281
       +
           let with_orcid = List.filter (fun c -> Contact.orcid c <> None) contacts |> List.length in

     

       282
       282
       +
           let with_url = List.filter (fun c -> Contact.url c <> None) contacts |> List.length in

     

       283
       283
       +
           let with_feeds = List.filter (fun c -> Contact.atom_feeds c <> None) contacts |> List.length in

     

       284
       284
       +
       

     

       285
       285
       +
           Logs.app (fun m -> m "Contact Database Statistics:");

     

       286
       286
       +
           Logs.app (fun m -> m "  Total contacts: %d" total);

     

       287
       287
       +
           Logs.app (fun m -> m "  With email: %d (%.1f%%)" with_email (float_of_int with_email /. float_of_int total *. 100.));

     

       288
       288
       +
           Logs.app (fun m -> m "  With GitHub: %d (%.1f%%)" with_github (float_of_int with_github /. float_of_int total *. 100.));

     

       289
       289
       +
           Logs.app (fun m -> m "  With ORCID: %d (%.1f%%)" with_orcid (float_of_int with_orcid /. float_of_int total *. 100.));

     

       290
       290
       +
           Logs.app (fun m -> m "  With URL: %d (%.1f%%)" with_url (float_of_int with_url /. float_of_int total *. 100.));

     

       291
       291
       +
           Logs.app (fun m -> m "  With Atom feeds: %d (%.1f%%)" with_feeds (float_of_int with_feeds /. float_of_int total *. 100.));

     

       292
       292
       +
           0

     

       293
       293
       +
       

     

       294
       294
       +
         (* Command info objects *)

     

       295
       295
       +
         let list_info = Cmd.info "list" ~doc:"List all contacts"

     

       296
       296
       +
       

     

       297
       297
       +
         let show_info = Cmd.info "show" ~doc:"Show detailed information about a contact"

     

       298
       298
       +
       

     

       299
       299
       +
         let search_info = Cmd.info "search" ~doc:"Search contacts by name"

     

       300
       300
       +
       

     

       301
       301
       +
         let stats_info = Cmd.info "stats" ~doc:"Show statistics about the contact database"

     

       302
       302
       +
       

     

       303
       303
       +
         (* Argument definitions *)

     

       304
       304
       +
         let handle_arg =

     

       305
       305
       +
           Arg.(required & pos 0 (some string) None & info [] ~docv:"HANDLE"

     

       306
       306
       +
             ~doc:"Contact handle to display")

     

       307
       307
       +
       

     

       308
       308
       +
         let query_arg =

     

       309
       309
       +
           Arg.(required & pos 0 (some string) None & info [] ~docv:"QUERY"

     

       310
       310
       +
             ~doc:"Name or partial name to search for")

     

       311
       311
       +
       end

+323

stack/sortal/lib/sortal.mli

···

       1
       1
       +
       (** Sortal - Username to metadata mapping with XDG storage

     

       2
       2
       +
       

     

       3
       3
       +
           This library provides a system for mapping usernames to various metadata

     

       4
       4
       +
           including URLs, emails, ORCID identifiers, and social media handles.

     

       5
       5
       +
           It uses XDG Base Directory Specification for storage locations and

     

       6
       6
       +
           jsont for JSON encoding/decoding.

     

       7
       7
       +
       

     

       8
       8
       +
           {b Storage:}

     

       9
       9
       +
       

     

       10
       10
       +
           Contact metadata is stored as JSON files in the XDG data directory,

     

       11
       11
       +
           with one file per contact using the handle as the filename.

     

       12
       12
       +
       

     

       13
       13
       +
           {b Typical Usage:}

     

       14
       14
       +
       

     

       15
       15
       +
           {[

     

       16
       16
       +
             let store = Sortal.create env#fs "myapp" in

     

       17
       17
       +
             let contact = Sortal.Contact.make

     

       18
       18
       +
               ~handle:"avsm"

     

       19
       19
       +
               ~names:["Anil Madhavapeddy"]

     

       20
       20
       +
               ~email:"anil@recoil.org"

     

       21
       21
       +
               ~github:"avsm"

     

       22
       22
       +
               ~orcid:"0000-0002-7890-1234"

     

       23
       23
       +
               () in

     

       24
       24
       +
             Sortal.save store contact;

     

       25
       25
       +
       

     

       26
       26
       +
             match Sortal.lookup store "avsm" with

     

       27
       27
       +
             | Some c -> Printf.printf "Found: %s\n" (Sortal.Contact.name c)

     

       28
       28
       +
             | None -> Printf.printf "Not found\n"

     

       29
       29
       +
           ]}

     

       30
       30
       +
       *)

     

       31
       31
       +
       

     

       32
       32
       +
       (** {1 Contact Metadata} *)

     

       33
       33
       +
       

     

       34
       34
       +
       module Contact : sig

     

       35
       35
       +
         (** Individual contact metadata.

     

       36
       36
       +
       

     

       37
       37
       +
             A contact represents metadata about a person, including their name(s),

     

       38
       38
       +
             social media handles, professional identifiers, and other contact information. *)

     

       39
       39
       +
         type t

     

       40
       40
       +
       

     

       41
       41
       +
         (** [make ~handle ~names ?email ?icon ?github ?twitter ?bluesky ?mastodon

     

       42
       42
       +
                 ?orcid ?url ?atom_feeds ()] creates a new contact.

     

       43
       43
       +
       

     

       44
       44
       +
             @param handle A unique identifier/username for this contact (required)

     

       45
       45
       +
             @param names A list of names for this contact, with the first being primary (required)

     

       46
       46
       +
             @param email Email address

     

       47
       47
       +
             @param icon URL to an avatar/icon image

     

       48
       48
       +
             @param github GitHub username (without the [\@] prefix)

     

       49
       49
       +
             @param twitter Twitter/X username (without the [\@] prefix)

     

       50
       50
       +
             @param bluesky Bluesky handle

     

       51
       51
       +
             @param mastodon Mastodon handle (including instance)

     

       52
       52
       +
             @param orcid ORCID identifier

     

       53
       53
       +
             @param url Personal or professional website URL

     

       54
       54
       +
             @param atom_feeds List of Atom/RSS feed URLs associated with this contact

     

       55
       55
       +
             *)

     

       56
       56
       +
         val make :

     

       57
       57
       +
           handle:string ->

     

       58
       58
       +
           names:string list ->

     

       59
       59
       +
           ?email:string ->

     

       60
       60
       +
           ?icon:string ->

     

       61
       61
       +
           ?github:string ->

     

       62
       62
       +
           ?twitter:string ->

     

       63
       63
       +
           ?bluesky:string ->

     

       64
       64
       +
           ?mastodon:string ->

     

       65
       65
       +
           ?orcid:string ->

     

       66
       66
       +
           ?url:string ->

     

       67
       67
       +
           ?atom_feeds:string list ->

     

       68
       68
       +
           unit ->

     

       69
       69
       +
           t

     

       70
       70
       +
       

     

       71
       71
       +
         (** {2 Accessors} *)

     

       72
       72
       +
       

     

       73
       73
       +
         (** [handle t] returns the unique handle/username. *)

     

       74
       74
       +
         val handle : t -> string

     

       75
       75
       +
       

     

       76
       76
       +
         (** [names t] returns all names associated with this contact. *)

     

       77
       77
       +
         val names : t -> string list

     

       78
       78
       +
       

     

       79
       79
       +
         (** [name t] returns the primary (first) name. *)

     

       80
       80
       +
         val name : t -> string

     

       81
       81
       +
       

     

       82
       82
       +
         (** [email t] returns the email address if available. *)

     

       83
       83
       +
         val email : t -> string option

     

       84
       84
       +
       

     

       85
       85
       +
         (** [icon t] returns the icon/avatar URL if available. *)

     

       86
       86
       +
         val icon : t -> string option

     

       87
       87
       +
       

     

       88
       88
       +
         (** [github t] returns the GitHub username if available. *)

     

       89
       89
       +
         val github : t -> string option

     

       90
       90
       +
       

     

       91
       91
       +
         (** [twitter t] returns the Twitter/X username if available. *)

     

       92
       92
       +
         val twitter : t -> string option

     

       93
       93
       +
       

     

       94
       94
       +
         (** [bluesky t] returns the Bluesky handle if available. *)

     

       95
       95
       +
         val bluesky : t -> string option

     

       96
       96
       +
       

     

       97
       97
       +
         (** [mastodon t] returns the Mastodon handle if available. *)

     

       98
       98
       +
         val mastodon : t -> string option

     

       99
       99
       +
       

     

       100
       100
       +
         (** [orcid t] returns the ORCID identifier if available. *)

     

       101
       101
       +
         val orcid : t -> string option

     

       102
       102
       +
       

     

       103
       103
       +
         (** [url t] returns the personal/professional website URL if available. *)

     

       104
       104
       +
         val url : t -> string option

     

       105
       105
       +
       

     

       106
       106
       +
         (** [atom_feeds t] returns the list of Atom/RSS feed URLs if available. *)

     

       107
       107
       +
         val atom_feeds : t -> string list option

     

       108
       108
       +
       

     

       109
       109
       +
         (** {2 Derived Information} *)

     

       110
       110
       +
       

     

       111
       111
       +
         (** [best_url t] returns the best available URL for this contact.

     

       112
       112
       +
       

     

       113
       113
       +
             Priority order:

     

       114
       114
       +
             1. Personal URL (if set)

     

       115
       115
       +
             2. GitHub profile URL (if GitHub username is set)

     

       116
       116
       +
             3. Email as mailto: link (if email is set)

     

       117
       117
       +
             4. None if no URL-like information is available

     

       118
       118
       +
             *)

     

       119
       119
       +
         val best_url : t -> string option

     

       120
       120
       +
       

     

       121
       121
       +
         (** {2 JSON Encoding} *)

     

       122
       122
       +
       

     

       123
       123
       +
         (** [json_t] is the jsont encoder/decoder for contacts.

     

       124
       124
       +
       

     

       125
       125
       +
             The JSON schema includes all contact fields with optional values

     

       126
       126
       +
             omitted when not present:

     

       127
       127
       +
             {[

     

       128
       128
       +
               {

     

       129
       129
       +
                 "handle": "avsm",

     

       130
       130
       +
                 "names": ["Anil Madhavapeddy"],

     

       131
       131
       +
                 "email": "anil@recoil.org",

     

       132
       132
       +
                 "github": "avsm",

     

       133
       133
       +
                 "orcid": "0000-0002-7890-1234"

     

       134
       134
       +
               }

     

       135
       135
       +
             ]}

     

       136
       136
       +
             *)

     

       137
       137
       +
         val json_t : t Jsont.t

     

       138
       138
       +
       

     

       139
       139
       +
         (** {2 Utilities} *)

     

       140
       140
       +
       

     

       141
       141
       +
         (** [compare a b] compares two contacts by their handles. *)

     

       142
       142
       +
         val compare : t -> t -> int

     

       143
       143
       +
       

     

       144
       144
       +
         (** [pp ppf t] pretty prints a contact with formatting. *)

     

       145
       145
       +
         val pp : Format.formatter -> t -> unit

     

       146
       146
       +
       end

     

       147
       147
       +
       

     

       148
       148
       +
       (** {1 Contact Store} *)

     

       149
       149
       +
       

     

       150
       150
       +
       (** The contact store manages reading and writing contact metadata

     

       151
       151
       +
           using XDG-compliant storage locations. *)

     

       152
       152
       +
       type t

     

       153
       153
       +
       

     

       154
       154
       +
       (** [create fs app_name] creates a new contact store.

     

       155
       155
       +
       

     

       156
       156
       +
           The store will use XDG data directories for persistent storage

     

       157
       157
       +
           of contact metadata. Each contact is stored as a separate JSON

     

       158
       158
       +
           file named after its handle.

     

       159
       159
       +
       

     

       160
       160
       +
           @param fs Eio filesystem for file operations

     

       161
       161
       +
           @param app_name Application name for XDG directory structure

     

       162
       162
       +
           *)

     

       163
       163
       +
       val create : Eio.Fs.dir_ty Eio.Path.t -> string -> t

     

       164
       164
       +
       

     

       165
       165
       +
       (** {2 Storage Operations} *)

     

       166
       166
       +
       

     

       167
       167
       +
       (** [save t contact] saves a contact to the store.

     

       168
       168
       +
       

     

       169
       169
       +
           The contact is serialized to JSON and written to a file

     

       170
       170
       +
           named "handle.json" in the XDG data directory.

     

       171
       171
       +
       

     

       172
       172
       +
           If a contact with the same handle already exists, it is overwritten.

     

       173
       173
       +
           *)

     

       174
       174
       +
       val save : t -> Contact.t -> unit

     

       175
       175
       +
       

     

       176
       176
       +
       (** [lookup t handle] retrieves a contact by handle.

     

       177
       177
       +
       

     

       178
       178
       +
           Searches for a file named "handle.json" in the XDG data directory

     

       179
       179
       +
           and deserializes it if found.

     

       180
       180
       +
       

     

       181
       181
       +
           @return [Some contact] if found, [None] if not found or deserialization fails

     

       182
       182
       +
           *)

     

       183
       183
       +
       val lookup : t -> string -> Contact.t option

     

       184
       184
       +
       

     

       185
       185
       +
       (** [delete t handle] removes a contact from the store.

     

       186
       186
       +
       

     

       187
       187
       +
           Deletes the file "handle.json" from the XDG data directory.

     

       188
       188
       +
           Does nothing if the contact does not exist.

     

       189
       189
       +
           *)

     

       190
       190
       +
       val delete : t -> string -> unit

     

       191
       191
       +
       

     

       192
       192
       +
       (** [list t] returns all contacts in the store.

     

       193
       193
       +
       

     

       194
       194
       +
           Scans the XDG data directory for all .json files and attempts

     

       195
       195
       +
           to deserialize them as contacts. Files that fail to parse are

     

       196
       196
       +
           silently skipped.

     

       197
       197
       +
       

     

       198
       198
       +
           @return A list of all successfully loaded contacts

     

       199
       199
       +
           *)

     

       200
       200
       +
       val list : t -> Contact.t list

     

       201
       201
       +
       

     

       202
       202
       +
       (** {2 Searching} *)

     

       203
       203
       +
       

     

       204
       204
       +
       (** [find_by_name t name] searches for contacts by name.

     

       205
       205
       +
       

     

       206
       206
       +
           Performs a case-insensitive search through all contacts,

     

       207
       207
       +
           checking if any of their names match the provided name.

     

       208
       208
       +
       

     

       209
       209
       +
           @param name The name to search for (case-insensitive)

     

       210
       210
       +
           @return The matching contact if exactly one match is found

     

       211
       211
       +
           @raise Not_found if no contacts match the name

     

       212
       212
       +
           @raise Invalid_argument if multiple contacts match the name

     

       213
       213
       +
           *)

     

       214
       214
       +
       val find_by_name : t -> string -> Contact.t

     

       215
       215
       +
       

     

       216
       216
       +
       (** [find_by_name_opt t name] searches for contacts by name, returning an option.

     

       217
       217
       +
       

     

       218
       218
       +
           Like {!find_by_name} but returns [None] instead of raising exceptions

     

       219
       219
       +
           when no match or multiple matches are found.

     

       220
       220
       +
       

     

       221
       221
       +
           @param name The name to search for (case-insensitive)

     

       222
       222
       +
           @return [Some contact] if exactly one match is found, [None] otherwise

     

       223
       223
       +
           *)

     

       224
       224
       +
       val find_by_name_opt : t -> string -> Contact.t option

     

       225
       225
       +
       

     

       226
       226
       +
       (** {2 Utilities} *)

     

       227
       227
       +
       

     

       228
       228
       +
       (** [handle_of_name name] generates a handle from a full name.

     

       229
       229
       +
       

     

       230
       230
       +
           Creates a handle by concatenating the initials of all words

     

       231
       231
       +
           in the name with the full last name, all in lowercase.

     

       232
       232
       +
       

     

       233
       233
       +
           Examples:

     

       234
       234
       +
           - "Anil Madhavapeddy" -> "ammadhavapeddy"

     

       235
       235
       +
           - "John Smith" -> "jssmith"

     

       236
       236
       +
       

     

       237
       237
       +
           @param name The full name to convert

     

       238
       238
       +
           @return A suggested handle

     

       239
       239
       +
           *)

     

       240
       240
       +
       val handle_of_name : string -> string

     

       241
       241
       +
       

     

       242
       242
       +
       (** {2 Convenience Functions} *)

     

       243
       243
       +
       

     

       244
       244
       +
       (** [create_from_xdg xdg] creates a contact store from an XDG context.

     

       245
       245
       +
       

     

       246
       246
       +
           This is a convenience function for creating a store when you already

     

       247
       247
       +
           have an XDG context (e.g., from eiocmd or your own XDG initialization).

     

       248
       248
       +
           The store will use the XDG data directory for the application.

     

       249
       249
       +
       

     

       250
       250
       +
           @param xdg An existing XDG context

     

       251
       251
       +
           @return A contact store using the XDG data directory

     

       252
       252
       +
           *)

     

       253
       253
       +
       val create_from_xdg : Xdge.t -> t

     

       254
       254
       +
       

     

       255
       255
       +
       (** [search_all t query] searches for contacts matching a query string.

     

       256
       256
       +
       

     

       257
       257
       +
           Performs a flexible search through all contact names, looking for:

     

       258
       258
       +
           - Exact matches (case-insensitive)

     

       259
       259
       +
           - Names that start with the query

     

       260
       260
       +
           - Multi-word names where any word starts with the query

     

       261
       261
       +
       

     

       262
       262
       +
           This is useful for autocomplete or fuzzy search functionality.

     

       263
       263
       +
       

     

       264
       264
       +
           @param t The contact store

     

       265
       265
       +
           @param query The search query (case-insensitive)

     

       266
       266
       +
           @return A list of matching contacts, sorted by handle

     

       267
       267
       +
           *)

     

       268
       268
       +
       val search_all : t -> string -> Contact.t list

     

       269
       269
       +
       

     

       270
       270
       +
       (** {2 Pretty Printing} *)

     

       271
       271
       +
       

     

       272
       272
       +
       (** [pp ppf t] pretty prints the contact store showing statistics. *)

     

       273
       273
       +
       val pp : Format.formatter -> t -> unit

     

       274
       274
       +
       

     

       275
       275
       +
       (** {1 Cmdliner Integration} *)

     

       276
       276
       +
       

     

       277
       277
       +
       module Cmd : sig

     

       278
       278
       +
         (** Cmdliner terms and commands for contact management.

     

       279
       279
       +
       

     

       280
       280
       +
             This module provides ready-to-use Cmdliner terms for building

     

       281
       281
       +
             CLI applications that work with contact metadata. *)

     

       282
       282
       +
       

     

       283
       283
       +
         (** [list_cmd] is a Cmdliner command that lists all contacts.

     

       284
       284
       +
       

     

       285
       285
       +
             Usage: Integrate into your CLI with [Cmd.group] or use standalone.

     

       286
       286
       +
             Requires eiocmd setup (env, xdg, profile parameters). *)

     

       287
       287
       +
         val list_cmd : unit -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)

     

       288
       288
       +
       

     

       289
       289
       +
         (** [show_cmd handle] creates a command to show detailed contact information.

     

       290
       290
       +
       

     

       291
       291
       +
             @param handle The contact handle to display *)

     

       292
       292
       +
         val show_cmd : string -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)

     

       293
       293
       +
       

     

       294
       294
       +
         (** [search_cmd query] creates a command to search contacts by name.

     

       295
       295
       +
       

     

       296
       296
       +
             @param query The search query string *)

     

       297
       297
       +
         val search_cmd : string -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)

     

       298
       298
       +
       

     

       299
       299
       +
         (** [stats_cmd] is a command that shows database statistics. *)

     

       300
       300
       +
         val stats_cmd : unit -> (Eio_unix.Stdenv.base -> Xdge.t -> 'a -> int)

     

       301
       301
       +
       

     

       302
       302
       +
         (** {2 Cmdliner Info Objects} *)

     

       303
       303
       +
       

     

       304
       304
       +
         (** [list_info] is the command info for the list command. *)

     

       305
       305
       +
         val list_info : Cmdliner.Cmd.info

     

       306
       306
       +
       

     

       307
       307
       +
         (** [show_info] is the command info for the show command. *)

     

       308
       308
       +
         val show_info : Cmdliner.Cmd.info

     

       309
       309
       +
       

     

       310
       310
       +
         (** [search_info] is the command info for the search command. *)

     

       311
       311
       +
         val search_info : Cmdliner.Cmd.info

     

       312
       312
       +
       

     

       313
       313
       +
         (** [stats_info] is the command info for the stats command. *)

     

       314
       314
       +
         val stats_info : Cmdliner.Cmd.info

     

       315
       315
       +
       

     

       316
       316
       +
         (** {2 Cmdliner Argument Definitions} *)

     

       317
       317
       +
       

     

       318
       318
       +
         (** [handle_arg] is the positional argument for a contact handle. *)

     

       319
       319
       +
         val handle_arg : string Cmdliner.Term.t

     

       320
       320
       +
       

     

       321
       321
       +
         (** [query_arg] is the positional argument for a search query. *)

     

       322
       322
       +
         val query_arg : string Cmdliner.Term.t

     

       323
       323
       +
       end

+119

stack/sortal/scripts/import_yaml_contacts.py

···

       1
       1
       +
       #!/usr/bin/env python3

     

       2
       2
       +
       """

     

       3
       3
       +
       Import YAML contacts from arod-dream to Sortal JSON format.

     

       4
       4
       +
       

     

       5
       5
       +
       This script reads contacts from ~/src/git/avsm/arod-dream/data/contacts/

     

       6
       6
       +
       and converts them to JSON files in the XDG data directory for sortal.

     

       7
       7
       +
       """

     

       8
       8
       +
       

     

       9
       9
       +
       import os

     

       10
       10
       +
       import json

     

       11
       11
       +
       import yaml

     

       12
       12
       +
       from pathlib import Path

     

       13
       13
       +
       

     

       14
       14
       +
       def get_xdg_data_home():

     

       15
       15
       +
           """Get the XDG data home directory."""

     

       16
       16
       +
           xdg_data_home = os.environ.get('XDG_DATA_HOME')

     

       17
       17
       +
           if xdg_data_home:

     

       18
       18
       +
               return Path(xdg_data_home)

     

       19
       19
       +
           return Path.home() / '.local' / 'share'

     

       20
       20
       +
       

     

       21
       21
       +
       def parse_contact_md(file_path):

     

       22
       22
       +
           """Parse a markdown file with YAML front matter."""

     

       23
       23
       +
           with open(file_path, 'r') as f:

     

       24
       24
       +
               content = f.read()

     

       25
       25
       +
       

     

       26
       26
       +
           # Extract YAML front matter between ---

     

       27
       27
       +
           if content.startswith('---\n'):

     

       28
       28
       +
               parts = content.split('---\n', 2)

     

       29
       29
       +
               if len(parts) >= 2:

     

       30
       30
       +
                   yaml_content = parts[1]

     

       31
       31
       +
                   return yaml.safe_load(yaml_content)

     

       32
       32
       +
           return None

     

       33
       33
       +
       

     

       34
       34
       +
       def convert_to_sortal_format(yaml_data, handle):

     

       35
       35
       +
           """Convert YAML contact data to Sortal JSON format."""

     

       36
       36
       +
           sortal_contact = {

     

       37
       37
       +
               "handle": handle,

     

       38
       38
       +
               "names": yaml_data.get("names", [])

     

       39
       39
       +
           }

     

       40
       40
       +
       

     

       41
       41
       +
           # Optional fields

     

       42
       42
       +
           if "email" in yaml_data:

     

       43
       43
       +
               sortal_contact["email"] = yaml_data["email"]

     

       44
       44
       +
           if "icon" in yaml_data:

     

       45
       45
       +
               sortal_contact["icon"] = yaml_data["icon"]

     

       46
       46
       +
           if "github" in yaml_data:

     

       47
       47
       +
               sortal_contact["github"] = yaml_data["github"]

     

       48
       48
       +
           if "twitter" in yaml_data:

     

       49
       49
       +
               sortal_contact["twitter"] = yaml_data["twitter"]

     

       50
       50
       +
           if "bluesky" in yaml_data:

     

       51
       51
       +
               sortal_contact["bluesky"] = yaml_data["bluesky"]

     

       52
       52
       +
           if "mastodon" in yaml_data:

     

       53
       53
       +
               sortal_contact["mastodon"] = yaml_data["mastodon"]

     

       54
       54
       +
           if "orcid" in yaml_data:

     

       55
       55
       +
               sortal_contact["orcid"] = yaml_data["orcid"]

     

       56
       56
       +
           if "url" in yaml_data:

     

       57
       57
       +
               sortal_contact["url"] = yaml_data["url"]

     

       58
       58
       +
           if "atom" in yaml_data:

     

       59
       59
       +
               sortal_contact["atom_feeds"] = yaml_data["atom"]

     

       60
       60
       +
       

     

       61
       61
       +
           return sortal_contact

     

       62
       62
       +
       

     

       63
       63
       +
       def main():

     

       64
       64
       +
           # Source directory

     

       65
       65
       +
           source_dir = Path.home() / 'src' / 'git' / 'avsm' / 'arod-dream' / 'data' / 'contacts'

     

       66
       66
       +
       

     

       67
       67
       +
           # Destination directory (XDG data home for sortal)

     

       68
       68
       +
           xdg_data = get_xdg_data_home()

     

       69
       69
       +
           dest_dir = xdg_data / 'sortal'

     

       70
       70
       +
           dest_dir.mkdir(parents=True, exist_ok=True)

     

       71
       71
       +
       

     

       72
       72
       +
           print(f"Importing contacts from: {source_dir}")

     

       73
       73
       +
           print(f"Output directory: {dest_dir}")

     

       74
       74
       +
           print()

     

       75
       75
       +
       

     

       76
       76
       +
           if not source_dir.exists():

     

       77
       77
       +
               print(f"Error: Source directory does not exist: {source_dir}")

     

       78
       78
       +
               return 1

     

       79
       79
       +
       

     

       80
       80
       +
           imported_count = 0

     

       81
       81
       +
           error_count = 0

     

       82
       82
       +
       

     

       83
       83
       +
           # Process each .md file

     

       84
       84
       +
           for md_file in sorted(source_dir.glob('*.md')):

     

       85
       85
       +
               handle = md_file.stem

     

       86
       86
       +
       

     

       87
       87
       +
               try:

     

       88
       88
       +
                   yaml_data = parse_contact_md(md_file)

     

       89
       89
       +
                   if yaml_data is None:

     

       90
       90
       +
                       print(f"⚠ Skipping {handle}: No YAML front matter found")

     

       91
       91
       +
                       error_count += 1

     

       92
       92
       +
                       continue

     

       93
       93
       +
       

     

       94
       94
       +
                   # Convert to Sortal format

     

       95
       95
       +
                   sortal_contact = convert_to_sortal_format(yaml_data, handle)

     

       96
       96
       +
       

     

       97
       97
       +
                   # Write JSON file

     

       98
       98
       +
                   output_file = dest_dir / f"{handle}.json"

     

       99
       99
       +
                   with open(output_file, 'w') as f:

     

       100
       100
       +
                       json.dump(sortal_contact, f, indent=2, ensure_ascii=False)

     

       101
       101
       +
       

     

       102
       102
       +
                   name = sortal_contact.get('names', [handle])[0] if sortal_contact.get('names') else handle

     

       103
       103
       +
                   print(f"✓ Imported: {handle} ({name})")

     

       104
       104
       +
                   imported_count += 1

     

       105
       105
       +
       

     

       106
       106
       +
               except Exception as e:

     

       107
       107
       +
                   print(f"✗ Error importing {handle}: {e}")

     

       108
       108
       +
                   error_count += 1

     

       109
       109
       +
       

     

       110
       110
       +
           print()

     

       111
       111
       +
           print(f"Import complete!")

     

       112
       112
       +
           print(f"  Successfully imported: {imported_count}")

     

       113
       113
       +
           print(f"  Errors: {error_count}")

     

       114
       114
       +
           print(f"  Output directory: {dest_dir}")

     

       115
       115
       +
       

     

       116
       116
       +
           return 0 if error_count == 0 else 1

     

       117
       117
       +
       

     

       118
       118
       +
       if __name__ == '__main__':

     

       119
       119
       +
           exit(main())

stack/sortal/test/dune

···

       1
       1
       +
       (test

     

       2
       2
       +
        (name test_sortal)

     

       3
       3
       +
        (libraries eio eio_main sortal jsont jsont.bytesrw))

+167

stack/sortal/test/test_sortal.ml

···

       1
       1
       +
       (** Tests for the Sortal library *)

     

       2
       2
       +
       

     

       3
       3
       +
       open Eio.Std

     

       4
       4
       +
       

     

       5
       5
       +
       let test_contact_creation () =

     

       6
       6
       +
         let c = Sortal.Contact.make

     

       7
       7
       +
           ~handle:"test"

     

       8
       8
       +
           ~names:["Test User"; "T. User"]

     

       9
       9
       +
           ~email:"test@example.com"

     

       10
       10
       +
           ~github:"testuser"

     

       11
       11
       +
           () in

     

       12
       12
       +
         assert (Sortal.Contact.handle c = "test");

     

       13
       13
       +
         assert (Sortal.Contact.name c = "Test User");

     

       14
       14
       +
         assert (List.length (Sortal.Contact.names c) = 2);

     

       15
       15
       +
         assert (Sortal.Contact.email c = Some "test@example.com");

     

       16
       16
       +
         assert (Sortal.Contact.github c = Some "testuser");

     

       17
       17
       +
         assert (Sortal.Contact.twitter c = None);

     

       18
       18
       +
         traceln "✓ Contact creation works"

     

       19
       19
       +
       

     

       20
       20
       +
       let test_best_url () =

     

       21
       21
       +
         let c1 = Sortal.Contact.make

     

       22
       22
       +
           ~handle:"test1"

     

       23
       23
       +
           ~names:["Test 1"]

     

       24
       24
       +
           ~url:"https://example.com"

     

       25
       25
       +
           ~github:"test1"

     

       26
       26
       +
           () in

     

       27
       27
       +
         assert (Sortal.Contact.best_url c1 = Some "https://example.com");

     

       28
       28
       +
       

     

       29
       29
       +
         let c2 = Sortal.Contact.make

     

       30
       30
       +
           ~handle:"test2"

     

       31
       31
       +
           ~names:["Test 2"]

     

       32
       32
       +
           ~github:"test2"

     

       33
       33
       +
           () in

     

       34
       34
       +
         assert (Sortal.Contact.best_url c2 = Some "https://github.com/test2");

     

       35
       35
       +
       

     

       36
       36
       +
         let c3 = Sortal.Contact.make

     

       37
       37
       +
           ~handle:"test3"

     

       38
       38
       +
           ~names:["Test 3"]

     

       39
       39
       +
           ~email:"test3@example.com"

     

       40
       40
       +
           () in

     

       41
       41
       +
         assert (Sortal.Contact.best_url c3 = Some "mailto:test3@example.com");

     

       42
       42
       +
       

     

       43
       43
       +
         let c4 = Sortal.Contact.make

     

       44
       44
       +
           ~handle:"test4"

     

       45
       45
       +
           ~names:["Test 4"]

     

       46
       46
       +
           () in

     

       47
       47
       +
         assert (Sortal.Contact.best_url c4 = None);

     

       48
       48
       +
       

     

       49
       49
       +
         traceln "✓ Best URL selection works"

     

       50
       50
       +
       

     

       51
       51
       +
       let test_json_encoding () =

     

       52
       52
       +
         let c = Sortal.Contact.make

     

       53
       53
       +
           ~handle:"json_test"

     

       54
       54
       +
           ~names:["JSON Test"]

     

       55
       55
       +
           ~email:"json@example.com"

     

       56
       56
       +
           ~github:"jsontest"

     

       57
       57
       +
           ~orcid:"0000-0001-2345-6789"

     

       58
       58
       +
           () in

     

       59
       59
       +
       

     

       60
       60
       +
         match Jsont_bytesrw.encode_string Sortal.Contact.json_t c with

     

       61
       61
       +
         | Ok json_str ->

     

       62
       62
       +
             (match Jsont_bytesrw.decode_string Sortal.Contact.json_t json_str with

     

       63
       63
       +
              | Ok decoded ->

     

       64
       64
       +
                  assert (Sortal.Contact.handle decoded = "json_test");

     

       65
       65
       +
                  assert (Sortal.Contact.email decoded = Some "json@example.com");

     

       66
       66
       +
                  assert (Sortal.Contact.github decoded = Some "jsontest");

     

       67
       67
       +
                  assert (Sortal.Contact.orcid decoded = Some "0000-0001-2345-6789");

     

       68
       68
       +
                  traceln "✓ JSON encoding/decoding works"

     

       69
       69
       +
              | Error err ->

     

       70
       70
       +
                  failwith ("JSON decode failed: " ^ err))

     

       71
       71
       +
         | Error err ->

     

       72
       72
       +
             failwith ("JSON encode failed: " ^ err)

     

       73
       73
       +
       

     

       74
       74
       +
       let test_handle_generation () =

     

       75
       75
       +
         assert (Sortal.handle_of_name "John Smith" = "jssmith");

     

       76
       76
       +
         assert (Sortal.handle_of_name "Alice Barbara Cooper" = "abccooper");

     

       77
       77
       +
         assert (Sortal.handle_of_name "Bob" = "bbob");

     

       78
       78
       +
         traceln "✓ Handle generation works"

     

       79
       79
       +
       

     

       80
       80
       +
       let test_store_operations () =

     

       81
       81
       +
         Eio_main.run @@ fun env ->

     

       82
       82
       +
       

     

       83
       83
       +
         (* Create a store with a test app name *)

     

       84
       84
       +
         let store = Sortal.create env#fs "sortal-test" in

     

       85
       85
       +
       

     

       86
       86
       +
         (* Create test contacts *)

     

       87
       87
       +
         let c1 = Sortal.Contact.make

     

       88
       88
       +
           ~handle:"alice"

     

       89
       89
       +
           ~names:["Alice Anderson"]

     

       90
       90
       +
           ~email:"alice@example.com"

     

       91
       91
       +
           () in

     

       92
       92
       +
       

     

       93
       93
       +
         let c2 = Sortal.Contact.make

     

       94
       94
       +
           ~handle:"bob"

     

       95
       95
       +
           ~names:["Bob Brown"; "Robert Brown"]

     

       96
       96
       +
           ~github:"bobbrown"

     

       97
       97
       +
           () in

     

       98
       98
       +
       

     

       99
       99
       +
         (* Test save *)

     

       100
       100
       +
         Sortal.save store c1;

     

       101
       101
       +
         Sortal.save store c2;

     

       102
       102
       +
         traceln "✓ Saving contacts works";

     

       103
       103
       +
       

     

       104
       104
       +
         (* Test lookup *)

     

       105
       105
       +
         (match Sortal.lookup store "alice" with

     

       106
       106
       +
          | Some c ->

     

       107
       107
       +
              assert (Sortal.Contact.name c = "Alice Anderson");

     

       108
       108
       +
              traceln "✓ Lookup works"

     

       109
       109
       +
          | None -> failwith "Lookup failed to find saved contact");

     

       110
       110
       +
       

     

       111
       111
       +
         (* Test lookup of non-existent contact *)

     

       112
       112
       +
         (match Sortal.lookup store "nonexistent" with

     

       113
       113
       +
          | None -> traceln "✓ Lookup correctly returns None for missing contact"

     

       114
       114
       +
          | Some _ -> failwith "Lookup should return None for non-existent contact");

     

       115
       115
       +
       

     

       116
       116
       +
         (* Test list *)

     

       117
       117
       +
         let all = Sortal.list store in

     

       118
       118
       +
         assert (List.length all >= 2);

     

       119
       119
       +
         traceln "✓ List returns saved contacts (%d total)" (List.length all);

     

       120
       120
       +
       

     

       121
       121
       +
         (* Test find_by_name *)

     

       122
       122
       +
         let found = Sortal.find_by_name store "Bob Brown" in

     

       123
       123
       +
         assert (Sortal.Contact.handle found = "bob");

     

       124
       124
       +
         traceln "✓ Find by name works";

     

       125
       125
       +
       

     

       126
       126
       +
         (* Test find_by_name_opt *)

     

       127
       127
       +
         (match Sortal.find_by_name_opt store "Alice Anderson" with

     

       128
       128
       +
          | Some c ->

     

       129
       129
       +
              assert (Sortal.Contact.handle c = "alice");

     

       130
       130
       +
              traceln "✓ Find by name (optional) works"

     

       131
       131
       +
          | None -> failwith "find_by_name_opt failed");

     

       132
       132
       +
       

     

       133
       133
       +
         (match Sortal.find_by_name_opt store "Nobody" with

     

       134
       134
       +
          | None -> traceln "✓ Find by name (optional) returns None for missing"

     

       135
       135
       +
          | Some _ -> failwith "find_by_name_opt should return None");

     

       136
       136
       +
       

     

       137
       137
       +
         (* Test delete *)

     

       138
       138
       +
         Sortal.delete store "alice";

     

       139
       139
       +
         (match Sortal.lookup store "alice" with

     

       140
       140
       +
          | None -> traceln "✓ Delete works"

     

       141
       141
       +
          | Some _ -> failwith "Contact should have been deleted");

     

       142
       142
       +
       

     

       143
       143
       +
         (* Clean up remaining test contact *)

     

       144
       144
       +
         Sortal.delete store "bob";

     

       145
       145
       +
         traceln "✓ Test cleanup complete"

     

       146
       146
       +
       

     

       147
       147
       +
       let test_contact_compare () =

     

       148
       148
       +
         let c1 = Sortal.Contact.make ~handle:"alice" ~names:["Alice"] () in

     

       149
       149
       +
         let c2 = Sortal.Contact.make ~handle:"bob" ~names:["Bob"] () in

     

       150
       150
       +
         let c3 = Sortal.Contact.make ~handle:"alice" ~names:["Alice2"] () in

     

       151
       151
       +
       

     

       152
       152
       +
         assert (Sortal.Contact.compare c1 c2 < 0);

     

       153
       153
       +
         assert (Sortal.Contact.compare c2 c1 > 0);

     

       154
       154
       +
         assert (Sortal.Contact.compare c1 c3 = 0);

     

       155
       155
       +
         traceln "✓ Contact comparison works"

     

       156
       156
       +
       

     

       157
       157
       +
       let () =

     

       158
       158
       +
         traceln "\n=== Running Sortal Tests ===\n";

     

       159
       159
       +
       

     

       160
       160
       +
         test_contact_creation ();

     

       161
       161
       +
         test_best_url ();

     

       162
       162
       +
         test_json_encoding ();

     

       163
       163
       +
         test_handle_generation ();

     

       164
       164
       +
         test_contact_compare ();

     

       165
       165
       +
         test_store_operations ();

     

       166
       166
       +
       

     

       167
       167
       +
         traceln "\n=== All Tests Passed ===\n"