CalCalist/README.md

# CalCalist

Aggregate several calendars into one, and keep them in step.

CalCalist mirrors any number of CalDAV calendars, Google calendars and iCal feeds into a single calendar you subscribe to. The point is to subscribe to one calendar instead of several: an event created or edited in the aggregate travels back to the calendar it came from, so the aggregate is somewhere to work rather than a read-only noticeboard. CalDAV and Google are read/write in both directions; iCal feeds are read-only, because the protocol is.

## Install

```sh
cargo build --release
# target/release/calcalist
```

One runtime dependency is needed for CalDAV and iCal sync: **`pimsync` 0.5.x on `PATH`**.

Then check the environment, which is worth doing before writing any config:

```sh
calcalist doctor
```

## Configure

One TOML file at `$XDG_CONFIG_HOME/calcalist/calcalist.toml`, or wherever `--config` points. It holds **no secrets and no sync state**, so it is safe to
copy between machines. 

Credentials come from `*_command` fields: each is run through `sh -c` and the first line of its output is used. Point them at `secret-tool`, `pass`, `gpg -d`, or anything else that prints the secret.

```toml
version = 1
```

Each `[[endpoint]]` is one calendar, with an `id` you refer to it by elsewhere.

### CalDAV Endpoint

```toml
[[endpoint]]
id = "posteo"
type = "caldav"
url = "https://posteo.de:8443/calendars/you/abc123/work/"
username = "you@posteo.de"
secret_command = "secret-tool lookup service posteo user you@posteo.de"
```

`url` must name the calendar collection itself, not the server root. 

Rather than digging it out of a provider's web interface, ask the server — this prints a ready-to-paste block per calendar, with ids taken from the URL for you to rename:

```sh
calcalist discover https://posteo.de:8443/calendars/you/ \
  --username you@posteo.de --secret-command "secret-tool lookup service posteo"
```

## Google Calendar Endpoint

```toml
[[endpoint]]
id = "gcal"
type = "google"
calendar_id = "you@gmail.com"
client_id = "1234-abcd.apps.googleusercontent.com"
client_secret_command = "secret-tool lookup service google-calcalist"
# account = "you@gmail.com"   # only when logged in to more than one account
```

`calendar_id` is `primary`, or the calendar's own address — the "Calendar ID" under its settings in Google Calendar. See [Authorising Google](#authorising-google) for `client_id` and the secret.

## iCal Feed Endpoint

```toml
[[endpoint]]
id = "holidays"
type = "webcal"
url = "https://example.org/holidays.ics"
```

Always read-only. Give exactly one of `url` or `url_command`; the latter is for a feed whose address is itself a credential, such as Google's "secret address in iCal format".

## Aggregates

Each `[[aggregate]]` composes endpoints: several `sources` mirrored into one `target`.

```toml
[[aggregate]]
id = "unified"
target = "posteo"
sources = ["gcal", "holidays"]
default_sink = "gcal"

# Defaults, all optional:
conflict = "source_wins"      # the only policy; the origin calendar wins
propagate_deletes = true      # deleting a mirror deletes the original
max_delete_fraction = 0.2     # abort if more of the aggregate than this vanishes
```

The rules, all checked before anything is synchronised, with every problem reported in one pass:

- `target` must exist and be writable, so never an iCal feed.
- `target` must not also be one of its own `sources`.
- `sources` must be non-empty, and each must exist and be named once.
- `default_sink`, if given, must be one of the `sources` and must be writable. Leaving it out is a deliberate mode — see [Getting events to the right calendar](#getting-events-to-the-right-calendar).
- No endpoint may be called `local`, which is reserved for the routing marker.

## A complete example

A Google calendar and a public holiday feed, aggregated into a CalDAV calendar:

```toml
version = 1

[[endpoint]]
id = "gcal"
type = "google"
calendar_id = "primary"
client_id = "1234-abcd.apps.googleusercontent.com"
client_secret_command = "secret-tool lookup service google-calcalist"

[[endpoint]]
id = "holidays"
type = "webcal"
url = "https://www.officeholidays.com/ics/germany"

[[endpoint]]
id = "posteo"
type = "caldav"
url = "https://posteo.de:8443/calendars/you/abc123/unified/"
username = "you@posteo.de"
secret_command = "secret-tool lookup service posteo user you@posteo.de"

[[aggregate]]
id = "unified"
target = "posteo"
sources = ["gcal", "holidays"]
default_sink = "gcal"
```

# Authorising Google

Google requires an OAuth client of your own. This is the fiddliest part of the setup, so in full:

1. At [console.cloud.google.com](https://console.cloud.google.com), create a
   project — any name.
2. **APIs & Services → Library**, find **Google Calendar API**, enable it.
3. **OAuth consent screen**: choose **External**. Fill in the required fields. Under **Test users**, add your own Google address.
4. **Credentials → Create credentials → OAuth client ID**, and for **Application type** choose **Desktop app**.
5. Copy the client ID into `client_id`, and put the client secret somewhere `client_secret_command` can read it:

   ```sh
   secret-tool store --label="calcalist Google client secret" service google-calcalist
   ```

6. Authorise:

   ```sh
   calcalist google login gcal
   ```

   A browser opens; approve the request. CalCalist asks only for `https://www.googleapis.com/auth/calendar`. The refresh token is written into the state directory, never into your configuration.

**One login covers every endpoint on that account.** The authorisation is filed under the account it was granted for, not the endpoint that asked, so a second Google calendar on the same account needs no login of its own. Set `account` on an endpoint only when CalCalist is logged in to more than one account.

**While the consent screen is in Testing, Google expires refresh tokens after seven days.** An installation that worked last week then stops with nothing
having changed locally. Publish the consent screen to production to end this; `calcalist doctor` reports it either way.

## Getting events to the right calendar

An event mirrored from a source goes back to that source when you edit it — CalCalist tracks where each one came from. An event you *create* in the
aggregate belongs to nothing yet, and goes to the aggregate's `default_sink`.

To send one somewhere else, put the endpoint's id after an `@` **on a line of its own** in the event's notes:

```
Dentist, bring the referral

@gcal
```

The marker is removed before the event arrives. `calcalist status` prints the markers that would actually work, so you need not remember what is in the
config; a marker naming anything else is refused and reported rather than quietly filed under the default.

**To keep an event in the aggregate itself**, tag it `@local` — it then stays put even though a `default_sink` would have taken it, and the marker is
deliberately left in place so later cycles decide the same way. 

Leaving `default_sink` out of the aggregate entirely makes that the rule for every untagged event, so routing becomes opt-in. Such events live only in that calendar and cannot be rebuilt from a source, but they are ordinary events on that server, visible to every client subscribed to it.

A category matching an endpoint id works too. Note that *any* category on a new event is read as a routing instruction, so the notes marker is the safer form.

## What it does to your calendars

- **Deleting an event in the aggregate deletes it at its source**, unless `propagate_deletes = false`. A cycle that would remove more than   `max_delete_fraction` of the aggregate is refused until you pass `--force` — with a floor of three, so removing one or two events is never blocked.
- **Edited in both places since the last sync, the source wins.** The conflict is reported.
- **Alarms are always kept**, with no option to strip them. The tool exists so you subscribe to one calendar rather than several, so dropping reminders would disarm every one you have.
- **Mirroring never mails your guests.** On a Google target attendees are kept and Google is told not to notify; on a CalDAV target, which cannot be told
  that, the guest list is carried as inert data instead. Routing an event *you* created is the exception: that server invites its guests for real, which is the point of creating it.

## Run it

```sh
calcalist doctor    # environment and configuration
calcalist sync      # one cycle
```

To run it regularly, units ship in [systemd/](systemd/):

```sh
install -Dm644 systemd/calcalist.service ~/.config/systemd/user/calcalist.service
install -Dm644 systemd/calcalist.timer   ~/.config/systemd/user/calcalist.timer
systemctl --user daemon-reload
systemctl --user enable --now calcalist.timer
```

The service expects the binary at `~/.local/bin/calcalist`; edit `ExecStart` if yours is elsewhere. Only one cycle runs at a time — a timer firing while you are running `sync` by hand is refused, naming the process that holds the lock. A cycle that could not reach an endpoint exits non-zero on purpose, so a lapsed token shows up as a failed unit rather than passing unnoticed; `journalctl --user -u calcalist` has the report. If your secrets come from a
keyring needing an unlocked session, the timer only works while you are logged in.

## Commands

`--help` has the flags.

| Command | |
|---|---|
| `sync` | One cycle. `--dry-run` reports against current remote state without writing; `--force` overrides the mass-deletion guard. |
| `status` | Endpoints, aggregates, how much is mirrored, and the routing markers that work. |
| `doctor` | Checks the environment and configuration. Run it first. |
| `discover` | Lists a CalDAV server's calendars as endpoint blocks to paste. |
| `google login` | Authorises an account. |
| `aggregate retarget` | Moves an aggregate to a different target calendar. `sync` refuses on its own when the target changes under it, and points here. |
| `prune` | Reports local mirrors of endpoints no longer configured; removes them under `--force`. |

Exit codes: `0` all well, `1` something failed or an endpoint could not be reached.

## Where things are kept

Everything machine-local lives under `$XDG_STATE_HOME/calcalist`:

```
state.json                       event mappings, content hashes, sync cursors
lock                             held for the duration of a cycle
pimsync.conf                     generated on every sync; edits are overwritten
pimsync-status/                  pimsync's own record of what it has seen
vdir/<endpoint-id>/              the local mirror of each endpoint
google/accounts/<account>.json   refresh tokens, 0600
```

None of it belongs in a backup or a dotfiles repository — it is a cache, and a lost state file costs a re-materialisation rather than data. Copy the
configuration between machines; leave this behind.

## Known gaps

- **A failing `pimsync sync` stops the whole CalDAV leg.** Google endpoints are isolated from each other, but pimsync is a single process covering every
  CalDAV and feed pair, and a failure does not say which pair it belongs to.

## License

MIT. See [LICENSE](LICENSE).