clean readme

pimalaya · Apr 15, 2024 · 752cf68 · 752cf68
1 parent 69e5a76
commit 752cf68
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -4,15 +4,21 @@ CLI to synchronize, backup and restore emails, based on [`email-lib`](https://cr
 
 ![screenshot](https://pimalaya.org/neverest/cli/latest/screenshot.jpeg)
 
-*Disclaimer: the project is under active development, do not use in production before the final `v1.0.0`.*
+*The project is under active development, do not use in production before the final `v1.0.0` (or at least do some backups).*
 
 ## Features
 
-- [IMAP](https://pimalaya.org/neverest/cli/latest/configuration/imap.html) support
-- [Maildir](https://pimalaya.org/neverest/cli/latest/configuration/maildir.html) and [Notmuch](https://pimalaya.org/neverest/cli/latest/configuration/notmuch.html) support
-- Synchronization of two backends together (folders and emails)
-- Partial sync based on filters (folders name and envelopes date)
-- Restricted sync based on permissions (folder/flag/message create/update/delete)
+- Backends configuration via interactive [wizard](https://pimalaya.org/neverest/cli/latest/configuration/index.html#automatically-using-the-wizard).
+- Sync pairs of backend together ([IMAP](https://pimalaya.org/neverest/cli/latest/configuration/imap.html), [Maildir](https://pimalaya.org/neverest/cli/latest/configuration/maildir.html) and [Notmuch](https://pimalaya.org/neverest/cli/latest/configuration/notmuch.html) supported).
+- Partial sync based on [filters](https://pimalaya.org/neverest/cli/latest/configuration/index.html#folderfilter) (folder name, envelope date).
+- Restricted sync based on [permissions](https://pimalaya.org/neverest/cli/latest/configuration/index.html#leftrightfolderpermissions) (create/delete folder, update flag, create/update message).
+- Backup and restore using the [Maildir](https://pimalaya.org/neverest/cli/latest/configuration/maildir.html) backend.
+
+*Coming soon:*
+
+- *POP, JMAP and mbox support.*
+- *Editing configuration via wizard.*
+- *Native backup and restore support.*
 
 ## Installation
 
@@ -33,15 +39,89 @@ $ cargo install neverest
 $ nix-env -i neverest
 ```
 
-*See the [documentation](https://pimalaya.org/neverest/cli/latest/installation.html) for other installation methods.*
+*Please read the [documentation](https://pimalaya.org/neverest/cli/latest/installation.html) for other installation methods.*
 
 </td>
 </tr>
 </table>
 
 ## Configuration
 
-*Please read the [documentation](https://pimalaya.org/neverest/cli/latest/configuration/).*
+Just run `neverest`, the wizard will help you to configure your default account. You can also manually edit your configuration at `~/.config/neverest/config.toml`:
+
+<details>
+  <summary>config.sample.toml</summary>
+
+  ```toml
+  [accounts.example]
+
+  # The current `example` account will be used by default.
+  default = true
+
+  # Filter folders according to the given rules.
+  #
+  # folder.filter.include = ["INBOX", "Sent"]
+  # folder.filter.exclude = ["All Mails"]
+  folder.filter = "all"
+
+  # Filter envelopes according to the given rules.
+  #
+  # envelope.filter.before = "1990-12-31T23:59:60Z"
+  # envelope.filter.after = "1990-12-31T23:59:60Z"
+
+  # The left backend configuration.
+  #
+  # In this example, the left side acts as our local cache.
+  left.backend.type = "maildir"
+  left.backend.root-dir = "/tmp/example"
+
+  # The left backend permissions.
+  #
+  # Example of a full permissive backend (default behaviour):
+  left.folder.permissions.create = true
+  left.folder.permissions.delete = true
+  left.flag.permissions.update = true
+  left.message.permissions.create = true
+  left.message.permissions.delete = true
+
+  # The right backend configuration.
+  #
+  # In this example, the right side acts as our remote.
+  right.backend.type = "imap"
+  right.backend.host = "localhost"
+  right.backend.port = 3143
+  right.backend.login = "alice@localhost"
+
+  # The right backend password.
+  #
+  # right.backend.passwd.cmd = "echo password"
+  # right.backend.passwd.keyring = "password-keyring-entry"
+  right.backend.passwd.raw = "password"
+
+  # The right backend encryption.
+  #
+  # right.backend.encryption = "tls" # or true
+  # right.backend.encryption = "start-tls"
+  right.backend.encryption = "none" # or false
+
+  # The right backend permissions.
+  #
+  # In this example, we set up safe permissions by denying deletions
+  # remote side.
+  right.folder.permissions.delete = false
+  right.message.permissions.delete = false
+
+  # The right folder aliases
+  #
+  # In this example, we define custom folder aliases for the right
+  # side. They are useful when you need to map left and right folders
+  # together.
+  right.folder.aliases.inbox = "Inbox"
+  right.folder.aliases.sent = "Sent Mails"
+  ```
+</details>
+
+*Please read the [documentation](https://pimalaya.org/neverest/cli/latest/configuration/) for more detailed information.*
 
 ## Contributing
 
@@ -51,6 +131,8 @@ If you want to **propose a feature** or **fix a bug**, please send a patch to th
 
 If you just want to **discuss** about the project, feel free to join the [Matrix](https://matrix.org/) workspace [#pimalaya.neverest](https://matrix.to/#/#pimalaya.neverest:matrix.org) or contact me directly [@soywod](https://matrix.to/#/@soywod:matrix.org). You can also [subscribe](mailto:~soywod/[email protected]) or [unsubscribe](mailto:~soywod/[email protected]) to the [mailing list](https://lists.sr.ht/~soywod/pimalaya).
 
+*Please read the [contributing guide](https://pimalaya.org/neverest/cli/latest/contributing.html) for more detailed information.*
+
 ## Sponsoring
 
 [![nlnet](https://nlnet.nl/logo/banner-160x60.png)](https://nlnet.nl/project/Neverest/index.html)

diff --git a/config.sample.toml b/config.sample.toml
@@ -55,3 +55,11 @@ right.backend.encryption = "none" # or false
 # remote side.
 right.folder.permissions.delete = false
 right.message.permissions.delete = false
+
+# The right folder aliases
+#
+# In this example, we define custom folder aliases for the right
+# side. They are useful when you need to map left and right folders
+# together.
+right.folder.aliases.inbox = "Inbox"
+right.folder.aliases.sent = "Sent Mails"
diff --git a/src/backend/config.rs b/src/backend/config.rs
@@ -46,7 +46,7 @@ impl BackendGlobalConfig {
             Arc::new(email::account::config::AccountConfig {
                 name,
                 folder: Some(email::folder::config::FolderConfig {
-                    aliases: self.folder.clone().map(|c| c.aliases),
+                    aliases: self.folder.clone().and_then(|c| c.aliases),
                     sync: Some(email::folder::sync::config::FolderSyncConfig {
                         filter: folder_filter,
                         permissions: self.folder.map(|c| c.permissions).unwrap_or_default(),
@@ -102,8 +102,7 @@ pub enum BackendConfig {
 pub struct FolderBackendConfig {
     #[serde(default)]
     pub permissions: FolderSyncPermissions,
-    #[serde(default)]
-    pub aliases: HashMap<String, String>,
+    pub aliases: Option<HashMap<String, String>>,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]

diff --git a/src/config/mod.rs b/src/config/mod.rs
@@ -83,7 +83,7 @@ impl Config {
 
         use crate::{wizard_prompt, wizard_warn};
 
-        wizard_warn!("Cannot find existing configuration at {path:?}.");
+        wizard_warn!("Cannot find configuration at {}", path.display());
 
         let confirm = Confirm::new()
             .with_prompt(wizard_prompt!(

diff --git a/src/config/wizard.rs b/src/config/wizard.rs
@@ -136,6 +136,7 @@ mod test {
                         ..Default::default()
                     }),
                     folder: Some(FolderBackendConfig {
+                        aliases: Default::default(),
                         permissions: FolderSyncPermissions {
                             create: true,
                             delete: false,