├── .gitignore ├── .rpm └── saturn-cli.spec ├── CHANGELOG.md ├── Cargo.lock ├── Cargo.toml ├── ISSUES.md ├── LICENSE ├── Makefile ├── README.md ├── notification.png ├── src ├── bin │ ├── saturn.rs │ └── sui.rs ├── cli_processor.rs ├── config.rs ├── db │ ├── google.rs │ ├── google_macros.rs │ ├── memory.rs │ ├── mod.rs │ ├── remote.rs │ └── unixfile.rs ├── filenames.rs ├── lib.rs ├── oauth.rs ├── parsers │ ├── entry.rs │ ├── mod.rs │ ├── search.rs │ └── time.rs ├── record.rs ├── time.rs └── ui │ ├── consts.rs │ ├── layout.rs │ ├── mod.rs │ ├── state.rs │ └── types.rs ├── swap └── tui.png /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | -------------------------------------------------------------------------------- /.rpm/saturn-cli.spec: -------------------------------------------------------------------------------- 1 | %define __spec_install_post %{nil} 2 | %define __os_install_post %{_dbpath}/brp-compress 3 | %define debug_package %{nil} 4 | 5 | Name: saturn-cli 6 | Summary: saturn is a command-line interface to calendaring, supporting Google Calendar 7 | Version: @@VERSION@@ 8 | Release: @@RELEASE@@%{?dist} 9 | License: MIT 10 | Group: Applications/System 11 | Source0: %{name}-%{version}.tar.gz 12 | URL: https://github.com/erikh/saturn 13 | 14 | BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root 15 | 16 | %description 17 | %{summary} 18 | 19 | %prep 20 | %setup -q 21 | 22 | %install 23 | rm -rf %{buildroot} 24 | mkdir -p %{buildroot} 25 | cp -a * %{buildroot} 26 | 27 | %clean 28 | rm -rf %{buildroot} 29 | 30 | %files 31 | %defattr(-,root,root,-) 32 | %{_bindir}/* 33 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | - `v0.4.5`: 2 | - Library updates & fixes to chrono deprecation warnings 3 | - `v0.4.4`: 4 | - Fix an issue where all day events would be spam notified every day. 5 | - Google: recurring tasks always preferred the original start time, not the current time. 6 | - Fix using certain weekdays as time specifiers. 7 | - `v0.4.3`: 8 | - Fix an issue where notifications for other days at the same time of day would appear in `saturn notify`. 9 | - `v0.4.2`: 10 | - Fix an issue where ending times would be cast before start times when using the edit command. 11 | - `v0.4.1`: 12 | - Fix an issue which was preventing Google Calendar from recording recurring tasks. 13 | - `v0.4.0`: 14 | - Notifications are now durations; if they are not provided via `notify` entry clauses, they will not exist and you will not be notified. You can add notifications to existing calendar items with `edit`. 15 | - Many bugfixes to the MemoryDB implementation. **YOUR OLD MEMORYDB WILL NO LONGER WORK AND YOU SHOULD DELETE IT. FILE AN ISSUE IF YOU NEED A CONVERTER.** 16 | - Correct a problem where failing to load the DB (due to underlying data structure changes) would erase the DB's contents. 17 | - Support using day names for the following week of time. Please see the documentation under "Dates". 18 | - Add a parameter to allow the customization of the window used to query Google Calendar. `saturn config set-query-window`. 19 | - Fix issue with 24h time field preventing the configuration from being deserialized. 20 | - Errors that occur in `sui` are now much more consistent, easier to read, 21 | and should not make the program unusable. 22 | - Fixed another race condition plaguing launches of `$EDITOR` for edit commands in `sui`. 23 | - New search feature! See [README](README.md) for more. 24 | - `saturn dump` was renamed to `saturn show`. `dump` will be a new subcommand in the future. 25 | - Google Calendar notification settings are now honored. 26 | - Support fields in editor and google calendar implementations. Fields 27 | are now a map of string -> array of string and are shown in listing 28 | commands. 29 | - Fix an issue where all day tasks on sundays would not be shown 30 | - Several style changes to `sui`: 31 | - Replaced underlining today's tasks with coloring them in bright 32 | white, using dark gray for all others. 33 | - Highlighting in light green tasks that occur within the next hour. 34 | - Fix an issue where a bug would prevent recurring tasks from being entered into Google Calendar 35 | - `v0.3.6`: 36 | - Fix ` -V` version output as well as adjust some help text for the CLI processor. 37 | - Colorize outputs in `saturn list` commands. 38 | - `v0.3.5`: 39 | - Add a configuration feature to never use the 12 hour adjustment. 40 | - Only massage times in 12 hour format for today's date. Other dates time will be treated in 24h. 41 | - Fixed more issues with iCal IDs. This will need to be changed more fundamentally in 0.4.0. 42 | - `v0.3.4`: 43 | - Fix an issue where 24-hour time may not be represented properly after 44 | noon. Thanks to [@raphaelahrens](https://github.com/raphaelahrens) for the report. 45 | - `v0.3.3`: 46 | - Fixed an issue where editing a task would result in a crash 47 | - `v0.3.2`: 48 | - Fixed another issue with iCal information not be appropriately managed 49 | between database wipes. 50 | - `v0.3.1`: 51 | - Fixed issue with items registered at midnight on the current Sunday not 52 | showing up in the list of events. 53 | - Fixed issue with calendars not recording new information properly in 54 | Google after the local DB had been wiped. 55 | - `v0.3.0`: 56 | - Implemented `show ` / `show recur ` for `sui` which displays task properties. 57 | - Fixed alignment issues with state notifications in `sui`. 58 | - Increased column widths for `sui`'s ID column in the events tab. 59 | - Fixed a number of outstanding issues with recurring tasks. 60 | - `sui` now supports `edit ` syntax; use `edit recur ` to edit 61 | recurring tasks. Launches `$EDITOR` and works the same way as `saturn edit`. 62 | - `saturn edit` will now edit the properties for a calendar item. Launches 63 | `$EDITOR` and commits changes back to the local or remote DB. Use `-r` 64 | for recurring tasks. 65 | - `saturn dump` will now dump the properties of a calendar item. Use `-r` 66 | for recurring tasks. 67 | - Support date endings (`th`, `rd`, `st`, etc) in entry syntax. See docs 68 | for more. 69 | - Some style/color changes to `sui` 70 | - Changed the strategy that the home directory was found; now using the 71 | `dirs` crate. 72 | - `v0.2.0`: 73 | - Introduction of `sui`, a graphical TUI built with the same principles 74 | as `saturn`. Uses the same data and databases and configuration file, 75 | and works great with Google Calendar. 76 | - Improvement of recurring task management with Google Calendar. Not all 77 | bugs are snipped here, but the big ones are. 78 | - `midnight` and `noon` are now valid times in the entry language. 79 | - `saturn delete` can now take multiple IDs to delete at once. 80 | - `saturn notify` can now accept notification icons with the `--icon` flag. 81 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "saturn-cli" 3 | version = "0.4.5" 4 | edition = "2021" 5 | description = "saturn is a command-line interface to calendaring, supporting Google Calendar" 6 | authors = ["Erik Hollensbe "] 7 | license = "MIT" 8 | homepage = "https://github.com/erikh/saturn" 9 | repository = "https://github.com/erikh/saturn" 10 | keywords = [ "cli", "calendar" ] 11 | categories = [ "command-line-utilities" ] 12 | 13 | # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html 14 | 15 | [dependencies] 16 | lazy_static = "^1" 17 | notify-rust = "^4.9" 18 | anyhow = "^1" 19 | chrono = { version = "^0.4", features = [ "serde" ] } 20 | chrono-tz = "^0.8" 21 | serde = "^1" 22 | serde_derive = "^1" 23 | ciborium = "^0.2" 24 | clap = { version = "^4.4", features = [ "derive" ] } 25 | regex = "^1" 26 | fancy-duration = { version = "^0.6", features = [ "chrono" ] } 27 | ttygrid = "^0.3" 28 | nix = "^0.26" 29 | serde_yaml = "^0.9" 30 | tokio = { version = "^1", features = [ "full" ] } 31 | gcal = "^0.1" 32 | async-trait = "^0.1" 33 | ratatui = { version = "^0.23", features = [ "all-widgets" ] } 34 | crossterm = "^0.27" 35 | dirs = "^5" 36 | tempfile = "^3.8" 37 | 38 | [dev-dependencies] 39 | rand = "^0.8" 40 | 41 | [package.metadata.rpm] 42 | package = "saturn-cli" 43 | 44 | [package.metadata.rpm.cargo] 45 | buildflags = ["--release"] 46 | 47 | [package.metadata.rpm.targets] 48 | sui = { path = "/usr/bin/sui" } 49 | saturn = { path = "/usr/bin/saturn" } 50 | 51 | [profile.release] 52 | strip = true 53 | lto = true 54 | codegen-units = 24 55 | opt-level = 3 56 | -------------------------------------------------------------------------------- /ISSUES.md: -------------------------------------------------------------------------------- 1 | # List of saturn's issues 2 | 3 | ## CBOR database 4 | 5 | The CBOR database is really effective for maintaining small numbers of records, but for large volumes of recurring tasks, the cost to write the db (which has to be done entirely for every write) is very expensive. Reading it also gets expensive for large databases, sometimes to the point where my timing loops expect it to be done and start operating on the data, which is also an issue. 6 | 7 | ## Database Backends 8 | 9 | I primarily use it with google calendar. There are tests for both database models, but I am worried the memory database implementation is poorly tested. 10 | 11 | Google Calendar is also very slow. This is because of a number of issues: 12 | 13 | ### Too many requests for a single operation 14 | 15 | There are far too many requests for a single operation, this is largely impacted by the fact that we refresh the DB after every write. 16 | 17 | ### Many requests are needlessly made 18 | 19 | This is different than the above; we make lots of requests at the time of execution instead of just consulting the database, which makes the database somewhat pointless, but also ends up with large pockets of response latency against user queries. A mechanism that used TTLs to better manage when a read request in particular needs to be made would be better. 20 | 21 | ## Code Smells 22 | 23 | These are a few big issues that are impacting the whole codebase. 24 | 25 | ### macro use stinks 26 | 27 | The macros are used to unify `sui` and `saturn` operations in a lot of situations, as well as get around some typing issues. There are better solutions for this, and this is just a case of it creeping up and growing on me before I've had an opportunity to resolve it. The downsides are that it tends to make the compiler and rust-analyzer a little confused, and it's also probably generating much larger code. A traits system, maybe with enums in the right places, would be better here. 28 | 29 | ### tui + async 30 | 31 | This is a big problem that I don't know how to fix yet. TUI toolkits in rust are all expecting synchronous/threaded code. I have a function called `sit` which is a very bad behaving function; starting a whole tokio reactor just to run a function and clean it all up, just for the purposes of running async code in a sync environment. Not only is this probably hideously expensive and unnecessary, it's a huge wart and it's used everywhere. A good solution would either be a async TUI toolkit or a solution that separates the concerns of the async and sync code. 32 | 33 | ## Design 34 | 35 | - Saturn needs coloring on the current time's tasks in lists 36 | - sui needs a new layout. I hate it and a lot of the screen is wasted. 37 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License 2 | 3 | Copyright 2023 Erik Hollensbe 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of 6 | this software and associated documentation files (the "Software"), to deal in 7 | the Software without restriction, including without limitation the rights to 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 9 | of the Software, and to permit persons to whom the Software is furnished to do 10 | so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | release: 2 | cargo publish 3 | cargo rpm build 4 | cargo deb 5 | 6 | .PHONY: release 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # saturn: a calendar for CLI nerds 2 | 3 | **NOTE:** all docs here chase the `main` branch features. If you want docs for a specific version, go to the `README` for the appropriate tag. 4 | 5 | ## Special note about the status of this project 6 | 7 | Until this notice is removed, this project is on temporary hiatus. There are a number of design flaws with this program that I need to rectify; I use it daily but there are a lot of things I haven't had the time to address as I have other pressing matters. Once I come back to this, I plan to address these issue in a lump sum and release a new version. I am [cataloguing the issues](ISSUES.md) and you are welcome to follow along. Some of them are very systemic and will take some time to rectify. 8 | 9 | ## Description 10 | 11 | If you like the application, come to the issues list and voice your ideas and concerns. I have personally been using `saturn` and `sui` for some time alongside Google Calendar (for more complicated situations) with few issues outside of things that happen when developing software normally. 12 | 13 | Saturn provides you with a CLI interface to calendaring much in the way [taskwarrior](https://github.com/GothenburgBitFactory/taskwarrior) does with tasks. It also provides you with several methods to query and notify yourself of important appointments. It can act standalone or integrate fully with Google Calendar. 14 | 15 | [Here](https://asciinema.org/a/611459) is a short tour (via asciicast) of `saturn` and `sui` in the terminal. 16 | 17 | Saturn is also now providing a TUI as a separate program since release v0.2.0; `sui` will present a calendar in a terminal window and allow you to interact with it in similar ways to `saturn`. See below for the list of commands. 18 | 19 | Here is what it looks like: 20 | 21 | 22 | 23 | # Table of Contents 24 | 25 | - [Installation](#installation) 26 | - [Cargo](#cargo) 27 | - [System Packages](#system-packages) 28 | - [Entry language](#entry-language) 29 | - [Formats](#formats) 30 | - [Dates](#dates) 31 | - [Times](#times) 32 | - [Durations](#durations) 33 | - [Querying](#querying) 34 | - [Listing](#listing) 35 | - [Notifying](#notifying) 36 | - [Editing](#editing) 37 | - [Deletion and Mutation](#deletion-and-mutation) 38 | - [Search](#search) 39 | - [Database & Configuration File](#database--configuration-file) 40 | - [Leveraging the well features with a periodic scheduler](#leveraging-the-well-features-with-a-periodic-scheduler) 41 | - [Recurring tasks](#recurring-tasks) 42 | - [Google Calendar Support](#google-calendar-support) 43 | - [TUI Commands](#tui-commands) 44 | - [Target Platform](#target-platform) 45 | - [Author](#author) 46 | 47 | ## Installation 48 | 49 | ### Cargo 50 | 51 | Install with cargo: 52 | 53 | ``` 54 | cargo install saturn-cli 55 | ``` 56 | 57 | Track development with: 58 | 59 | ``` 60 | cargo install --git https://github.com/erikh/saturn 61 | ``` 62 | 63 | ### System Packages 64 | 65 | On NetBSD a pre-compiled package is available from the official repositories. To install it, simply run: 66 | 67 | ``` 68 | pkgin install saturn-cli 69 | ``` 70 | 71 | RPM and DEB format packages are usually shipped with the [GitHub Releases](https://github.com/erikh/saturn/releases). 72 | 73 | ## Entry language 74 | 75 | Entry language is basically: 76 | 77 | ``` 78 | ENTRY = [ "recur" ] ["notify" ] 79 | AT = at