# Changelog

All notable changes to busybar-calendar. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
[Semantic Versioning](https://semver.org/).

## [Unreleased]

## [0.8.0] - 2026-10-20

### Added

- Events you marked tentative ("Maybe") are drawn in yellow: a yellow calendar
  and a yellow `BUSY`, in the reminder and during the event, so they read
  differently from the events you accepted. `[display] tentative_yellow = false`
  draws them in red like the rest. With `reminder_icon` / `event_icon` set to
  `animation` only the label turns yellow, as the bar's own animation has no
  yellow version.

### Changed

- `scripts/capture_screens.py` draws the tentative status for the README, and
  its docs now say that a capture takes a running service's screen down until
  the service redraws.
- The screen is redrawn when you change your answer to an event that is
  already up - marked "maybe" from your phone, say - at the next refresh,
  not only when the screen changes.
- CI tests Python 3.12, 3.14 and 3.15 (it was 3.11, 3.12 and 3.13), and its
  actions run on Node 24. `requires-python` stays `>=3.11`, which is no
  longer tested.

## [0.7.2] - 2026-10-13

### Fixed

- `restart` on macOS waited up to five minutes when the service had
  started recently: `launchctl kickstart -k` waits out the agent's restart
  throttle. It now unloads the agent and loads it again, which starts it
  at once - and also works for an agent that was not loaded. With
  `--auto-update`, that makes `restart` the quick way to update.

## [0.7.1] - 2026-10-13

### Fixed

- `install` over a running launch agent could fail with
  `launchctl bootstrap ... failed (exit 5)`, leaving the service stopped:
  `launchctl bootout` returns before the old agent is gone. `install` now
  waits for it (up to 10 seconds) before loading the new one.

## [0.7.0] - 2026-10-13

### Added

- `busybar-calendar install --auto-update`: the background service updates
  itself every time it starts - at login, on `restart`, after it stopped -
  with `uv tool upgrade busybar-calendar`, before it reads the config, then
  runs the new version at once. A failed update (no network yet at login)
  starts the version it has. It needs the one-line install from git, and
  `install` says so when it is not that. `status` shows
  `updates itself at each start`, and `--json` has `service.auto_update`.
- `run --auto-update`, what such a service runs.

## [0.6.1] - 2026-10-13

### Fixed

- A CalDAV account lists its calendars again every hour, to find new
  ones; a timeout or server error at that moment no longer drops the whole
  refresh. It goes on with the calendars it knows, says so in the log, and
  lists them again at the next refresh. A refused password still stops the
  service, as before.

## [0.6.0] - 2026-10-13

### Added

- `upcoming` names the `[[titles]]` patterns that apply to each event, so a
  rule that hides or changes one shows why: `(hidden, titles 'Focus*')`.

### Fixed

- `upcoming` no longer lists `status` for a tentative event when
  `status.tentative` is off; it shows only the reminder, as the bar does.

## [0.5.1] - 2026-10-13

### Fixed

- `status`, and `busybar-calendar` on its own, report a config that does
  not load - with its problems and the fact that a running service keeps
  the config it last loaded - instead of stopping at the first error and
  showing nothing about the service. `status` exits 1 then, and its
  `--json` has a `config` block with the path and the problems.

## [0.5.0] - 2026-10-13

### Added

- A running service follows edits to its config: they apply within a
  minute, with the calendars read again at once and the screen redrawn
  (without a second chime). An edit that does not load leaves the service
  on the config it has, and the log says what is wrong; a change under
  `[bar]` waits for `busybar-calendar restart`.

## [0.4.0] - 2026-10-13

### Added

- `[[titles]]` rules: reminder and status settings for the events whose
  title matches (`*` and `?` wildcards, any case), from any calendar, on top
  of the calendar's own - to keep `Focus time` off the bar, or show `Lunch*`
  as the bar's own lunch status. `upcoming` shows what each event ends up
  with, and `demo --title` draws with the rules for that title.

### Fixed

- A bad reminder or status value now says where it is
  (`sources.0.calendars.Team.reminder: minutes_before: ...`), not just which
  key.

## [0.3.2] - 2026-10-12

### Changed

- Install with one line, no clone needed:
  `uv tool install git+https://github.com/kurok/busybar-calendar`, and
  upgrade with `uv tool upgrade busybar-calendar`.

### Fixed

- `status` no longer offers `restart` as the way to a newer version when the
  service runs from another install (a checkout run with `uv run`, say): a
  restart would start the old version again. It names the install to upgrade,
  and the `uv tool upgrade` command when that install came from git.

## [0.3.1] - 2026-10-12

### Added

- `status` checks the bar with one light read-only call and says whether it
  answers, refuses the token, or does not answer at all - with what to do -
  so a stuck bar no longer looks like a healthy setup.

### Fixed

- Event titles are capped at 120 characters (a longer one only scrolls
  longer). A draw request with a title of thousands of characters left a
  bar's HTTP API hanging, on the LAN and through BUSY Cloud, until the bar
  was power-cycled.

## [0.3.0] - 2026-10-12

### Changed

- `init` and `add` ask for the calendar provider from a list - iCloud,
  Fastmail, PrivateEmail, Nextcloud or another server - guessed from your
  address, instead of for the server's URL; Nextcloud needs only its host.

### Added

- `busybar-calendar` on its own says where you stand: the first steps before
  there is a config, the status after, instead of a usage error.
- `status` shows the version the background service runs, read from the line
  it now logs at start, and says to `restart` when that is not the version
  installed; the setup guide has an "Upgrading" section.
- Tentative events in published feeds, which carry no attendees, now count as
  tentative: Outlook's busy status or `STATUS:TENTATIVE` decides there, for
  overlaps and for `status.tentative`.

### Fixed

- A Keychain / libsecret prompt that failed - a mistyped retype - ended
  `init` and `add` with a traceback; it is now asked again, up to three times,
  then reported in one line.
- A failing `launchctl` or `systemctl` ended `install` with a traceback; it is
  now one line naming the command and its exit code.
- The service remembered every screen it had chimed for; it now forgets
  them once their events are gone, so a long-running service does not grow.
- A mistyped `sync.timezone` ended every command in a traceback; it is now
  rejected when the config is read, with an example of a valid name.
- `calendars` and `replay` ended in a traceback when a calendar server could
  not be reached; they now say which address and why.
- A config mistake printed pydantic's whole report; it is now one line per
  problem, naming the key (`bar.adress: Extra inputs are not permitted`), in
  the CLI and in `app.py` alike.
- `app.py --minutes 0` (and other invalid reminder or status settings given
  as flags) was accepted and only failed at the first event; it now fails at
  start.

## [0.2.0] - 2026-10-12

### Added

- `busybar-calendar add`: another calendar source by the same questions as
  `init`, appended to the config with its comments and layout kept, under a
  name that does not clash with the others.
- `--json` for `status` and `check`: the service, the screen now and next,
  and each check's finding with its fields (firmware, calendars, next event),
  with times in ISO 8601.
- `busybar-calendar restart`, for the background service after a new
  password or config.
- [docs/troubleshooting.md](docs/troubleshooting.md): what `check` and
  `status` say for each common problem, from real failures, and the fix.

### Changed

- After `init` or `add`, an installed background service is restarted, so it
  reads the new config.
- `init` and `add` keep each account's password in a Keychain / libsecret
  entry of its own; two accounts on one domain no longer share one.

### Fixed

- `check` called a BUSY Cloud that refused the token "unreachable"; it now
  says the token is wrong, revoked or lacks the BUSY Bar scope.
- For a source whose `include` matched no calendar, `check` added a
  reassuring "no events in the next 7 days"; it now lists the calendars
  there are, and the source's own warnings no longer repeat in its output.

## [0.1.0] - 2026-10-12

The first release.

### Added

- Reminders and a BUSY status on the BUSY Bar from any CalDAV account
  (iCloud, Fastmail, Nextcloud, PrivateEmail, Radicale, ...) or ICS / webcal
  link, drawn through the bar's HTTP API on the LAN or through BUSY Cloud.
- The Google Calendar integration's per-calendar settings - reminder time,
  sound, show name, status during events - layered as defaults, per source
  and per calendar.
- A red calendar icon and a red BUSY beside the countdown during an event;
  the bar's own animations and statuses (`meeting`, `on_call`, ...) as
  options.
- Overlapping events settled by your response: accepted over tentative over
  not answered, then the newest event. `status.tentative` keeps tentative
  events off the busy status.
- Calendar filters: `include` / `exclude` by name, id or URL, with wildcards.
- Commands: `init` (a few questions write the config, passwords go to the
  Keychain or libsecret), `check` (the bar, its token and every calendar),
  `install` / `uninstall` (launchd or systemd), `status` (running? now and
  next), `calendars`, `upcoming`, `demo`, `replay`, `run`, `--version`.
- `app.py`, following the BUSY Bar community gallery's rules: `--host`,
  `--ics`, `--caldav`, `--demo`, `--test`, secrets from the environment.
- Docs with screenshots read back from a real bar, and a configuration
  reference generated from the code.

### Fixed

Found on a bar running firmware 1.2.4, and recorded in
[docs/how-it-works.md](docs/how-it-works.md):

- The countdown overlapped the title: its font sits 4px high in its box.
- The status lost its icon when it replaced a reminder as the reminder's
  `display_until` fired; drawings now outlive their screen by a minute.
- A draw merges by element id, so a new layout could land on top of the old
  one; a clear now comes first only when an element would be left over,
  and a reminder becomes its event without a blink.
- CalDAV discovery turned PROPFIND into GET on a 302 redirect.
- A 401 or 404 from a calendar was retried forever; it now stops the
  service with the reason.
- A refused draw (409) stopped the demo and replay.
- A Ctrl-C during the slow first start printed a traceback.

[Unreleased]: https://github.com/kurok/busybar-calendar/compare/v0.8.0...HEAD
[0.8.0]: https://github.com/kurok/busybar-calendar/compare/v0.7.2...v0.8.0
[0.7.2]: https://github.com/kurok/busybar-calendar/compare/v0.7.1...v0.7.2
[0.7.1]: https://github.com/kurok/busybar-calendar/compare/v0.7.0...v0.7.1
[0.7.0]: https://github.com/kurok/busybar-calendar/compare/v0.6.1...v0.7.0
[0.6.1]: https://github.com/kurok/busybar-calendar/compare/v0.6.0...v0.6.1
[0.6.0]: https://github.com/kurok/busybar-calendar/compare/v0.5.1...v0.6.0
[0.5.1]: https://github.com/kurok/busybar-calendar/compare/v0.5.0...v0.5.1
[0.5.0]: https://github.com/kurok/busybar-calendar/compare/v0.4.0...v0.5.0
[0.4.0]: https://github.com/kurok/busybar-calendar/compare/v0.3.2...v0.4.0
[0.3.2]: https://github.com/kurok/busybar-calendar/compare/v0.3.1...v0.3.2
[0.3.1]: https://github.com/kurok/busybar-calendar/compare/v0.3.0...v0.3.1
[0.3.0]: https://github.com/kurok/busybar-calendar/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/kurok/busybar-calendar/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/kurok/busybar-calendar/releases/tag/v0.1.0

Copyright 2013 Google LLC

This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
https://scripts.sil.org/OFL


-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------

PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.

The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded, 
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.

DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.

"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).

"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).

"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.

"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.

PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:

1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.

2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.

3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.

4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.

5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.

TERMINATION
This license becomes null and void if any of the above conditions are
not met.

DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.

# busybar-calendar

Calendar reminders for the [BUSY Bar](https://busy.app) from **any CalDAV
account or ICS feed**, shown exactly the way the bar shows its built-in
Google Calendar events.

![A reminder on the BUSY Bar: calendar icon, title and countdown](docs/images/reminder.gif)

The bar's own [Google Calendar integration](https://docs.busy.app/bar/apps-and-integrations/google-calendar)
runs in BUSY Cloud and only talks to Google. This does the same thing for
iCloud, Fastmail, Nextcloud, PrivateEmail, self-hosted CalDAV servers, and
any calendar published as an ICS link (Outlook, Google, Proton). It runs on
a machine of yours and draws through the bar's
[HTTP API](https://docs.busy.app/bar/dev/http-api), via BUSY Cloud or on the
LAN. The events look the same as Google's; only where they come from is
different. Requested upstream as
[busybar-firmware#1086](https://github.com/busy-app/busybar-firmware/issues/1086).

## On the bar

Every picture here is a frame read back from a real bar (firmware 1.2.4)
through `GET /api/screen`.

| | |
| --- | --- |
| **Before the event** - a red calendar, the title, and a countdown to the start. | ![Reminder](docs/images/reminder.gif) |
| **During the event** - a red calendar, the title, a countdown to the end and a red **BUSY** ... | ![Status with the event name](docs/images/status.png) |
| **Marked "Maybe"** (tentative): a yellow calendar and a yellow **BUSY**, in the reminder and during the event, so you can tell it from one you accepted. | ![Status of a tentative event](docs/images/status-tentative.png) |
| ... or one of the bar's own statuses, such as `meeting`, `on_call` or `dnd`. | ![Meeting status](docs/images/status-meeting.gif) |
| **Long titles** scroll beside the icon. | ![Scrolling title](docs/images/long-title.gif) |
| **Titles in other scripts** are transliterated for the bar's bitmap fonts (`Планування спринту` becomes `Planuvannya sprintu`) ... | ![Transliterated title](docs/images/cyrillic-transliterated.gif) |
| ... or drawn as they are with `title_font = "global"`, on one line beside the countdown. | ![Cyrillic title in the global font](docs/images/cyrillic-global.gif) |
| **Event name hidden** for a calendar (`show_name = false`). | ![Hidden name](docs/images/hidden-name.png) |

Like Google events, these go in above an active BUSY session, so they show
on top of any status. A sound plays as a reminder opens and as an event
starts, using the bar's own calendar sounds. After the event, the bar goes
back to whatever it was showing.

## Features

- **CalDAV** with discovery (`/.well-known/caldav`, principal, calendar home),
  or a calendar URL directly; Basic or Digest auth.
- **Calendar filters**: `include` / `exclude` by name, id or URL, with
  wildcards (`exclude = ["Room *"]`).
- **ICS / webcal** feeds, fetched with `If-None-Match`.
- **Recurring events** expanded locally (RRULE, EXDATE, moved occurrences),
  timezones and floating times handled.
- **Google's per-calendar settings** (reminder time, sound, show name,
  status), set once as defaults and overridden per source or per calendar.
- **Rules by title**, from any calendar: keep `Focus time` off the bar,
  show `Lunch*` as the bar's own lunch status.
- **Overlaps settled by your response**: an event you accepted wins over
  one you marked tentative, which wins over one you have not answered - when
  they start together and when they are shifted against each other, so a
  "maybe" never covers a meeting you said yes to; then, as in Google's
  integration, the newest event wins.
- **"Maybe" in yellow**: an event you marked tentative gets a yellow
  calendar and a yellow BUSY, so you can tell it from one you accepted
  (`display.tentative_yellow`, default on).
- **Google's filters**: no all-day or 24-hour-plus events. Also skipped:
  cancelled events, events marked free, invitations you declined.
- **On time**: the loop wakes at the next change, not on the next poll.
- **Live config**: the running service applies an edited config within a
  minute; an edit that does not load is left out, and the log says why.
- **Resilient**: a failing source keeps its last good events; a bar that
  cannot be reached is retried; drawings expire on the bar by themselves
  if the service stops.
- **No secrets in files**: passwords and tokens come from the environment
  or a command such as the macOS Keychain.

## Get started

```sh
uv tool install git+https://github.com/kurok/busybar-calendar
busybar-calendar init     # a few questions: how to reach the bar, which calendar
busybar-calendar check    # proves it works, or says what to fix
busybar-calendar install  # runs it in the background from now on
```

`init` asks how to reach the bar (BUSY Cloud, Wi-Fi or USB) and which
calendar to read, keeps the passwords in the macOS Keychain (libsecret on
Linux), signs in so you can pick calendars, and writes
`~/.config/busybar-calendar/config.toml`. To write the config yourself,
start from [`config.example.toml`](config.example.toml).

## Everyday commands

| Command | |
| --- | --- |
| `busybar-calendar` | Where you stand: the first steps before setup, the status after. |
| `busybar-calendar status` | Is it running, what did it last log, what is on the bar now and next. |
| `busybar-calendar check` | The bar, its token and every calendar, with what to fix. |
| `busybar-calendar add` | Another calendar, by the same questions as `init`. |
| `busybar-calendar restart` | After a new password or a `[bar]` change; other config edits apply by themselves within a minute. |
| `busybar-calendar upcoming` | The events the bar will show, and when; tentative ones marked. |
| `busybar-calendar calendars` | What each CalDAV account has, with ids, for `include`. |
| `busybar-calendar replay` | Tomorrow's events on the bar, a minute each. |
| `busybar-calendar demo` | A sample reminder on the bar, to see the look. |
| `busybar-calendar uninstall` | Stop and remove the background service. |

`status` and `check` also take `--json`, for scripts. A newer version is
`uv tool upgrade busybar-calendar && busybar-calendar restart` - or, with
`busybar-calendar install --auto-update`, the service fetches it by itself
every time it starts or restarts.

## As a BUSY Bar gallery app

`app.py` follows the [community gallery](https://github.com/maxswinkels/busybar-apps)'s
conventions: one entrypoint, `--host` (default `10.0.4.20`, the bar over
USB), secrets from the environment only. It runs from a clone:

```sh
git clone https://github.com/kurok/busybar-calendar.git && cd busybar-calendar
pip install -r requirements.txt
python app.py                        # the config init wrote; a demo schedule before that
python app.py --host 192.168.1.50 --ics "https://example.com/work.ics"
CALDAV_PASSWORD=... python app.py --caldav https://caldav.icloud.com --user me@icloud.com
BUSYBAR_TOKEN=... python app.py --cloud --ics "https://example.com/work.ics"
```

`CALDAV_PASSWORD` is the calendar's password, `BUSYBAR_TOKEN` the bar's HTTP
API password or, with `--cloud`, a BUSY Cloud token. On macOS the first
start after installing the requirements takes a few seconds while the system
checks the new libraries; later starts take a fraction of a second.

## Settings

The per-calendar settings are the Google Calendar integration's:

| Google Calendar integration | `config.toml` |
| --- | --- |
| Event reminders: on/off | `reminder.enabled` |
| How long before the event | `reminder.minutes_before` |
| Sound | `reminder.sound` |
| Show event name | `reminder.show_name` |
| Status during events: on/off | `status.enabled` |
| Event name, or a status from the list | `status.show`: `name`, `meeting`, `on_call`, `dnd`, ... |
| Sound | `status.sound` |
| *(not in Google's)* Busy status for events you marked tentative | `status.tentative` (default on) |
| *(not in Google's)* Yellow calendar and BUSY for events you marked tentative | `display.tentative_yellow` (default on) |

They layer: `[defaults]` for every calendar, then per source, then per
calendar (`[sources.calendars."Work".reminder]`); a default set once is the
account-level setting BUSY Cloud does not have yet
([busybar-firmware#1083](https://github.com/busy-app/busybar-firmware/issues/1083)).
Last come the `[[titles]]` rules, which match event titles in any calendar:

```toml
[[titles]]
match = ["Focus time", "Commute*"]   # * and ? are wildcards; case does not matter
reminder.enabled = false
status.enabled = false
```

`[display]` sets the look: the icons (`red_calendar` or the bar's own
`animation`), the word beside the countdown (`busy_label`, `busy_color`) and
whether events you marked tentative are drawn in yellow (`tentative_yellow`).
Every option, with its default, is in the
[configuration reference](docs/configuration.md).

## Documentation

- [Setup](docs/setup.md) - the bar, calendar providers, secrets, running as a service.
- [Troubleshooting](docs/troubleshooting.md) - what `check` and `status` say when something is wrong, and the fix.
- [Configuration reference](docs/configuration.md) - every option and its default, generated from the code.
- [Changelog](CHANGELOG.md) - what changed in each version.
- [How it works](docs/how-it-works.md) - the design, the API calls, and what was measured on the hardware.

## Development

```sh
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
```

`scripts/capture_screens.py` regenerates `docs/images` from a real bar.

## License

MIT, except the red and yellow calendar icons in `src/busybar_calendar/icons.py`:
they are redrawn from Google's [Noto Emoji](https://github.com/googlefonts/noto-emoji)
📅 and stay under the SIL Open Font License 1.1
([LICENSES/noto-emoji-OFL.txt](LICENSES/noto-emoji-OFL.txt)).

#!/usr/bin/env python3
"""CalDAV Calendar: meeting reminders and a red BUSY from any CalDAV or ICS calendar.

A countdown before each event, then the event's title with a countdown to its
end and a red BUSY while it runs; the bar is left alone between events.
CalDAV (iCloud, Fastmail, Nextcloud, PrivateEmail, Radicale, ...) or any ICS
link (Outlook "Publish a calendar", Google's secret iCal address).

    python app.py                                  # demo schedule, BUSY Bar over USB (10.0.4.20)
    python app.py --host 127.0.0.1:8080            # emulator or a Wi-Fi bar
    python app.py --ics https://example.com/work.ics
    python app.py --caldav https://caldav.icloud.com --user me@icloud.com --include Work
    python app.py --config config.toml             # every setting: see config.example.toml
                                                   # (without flags, the config that
                                                   # `busybar-calendar init` wrote is used)
    python app.py --test                           # draw one frame of an event and exit

Secrets come from the environment, never the command line or this file:

    CALDAV_PASSWORD   the CalDAV password (iCloud and Fastmail need an app password)
    BUSYBAR_TOKEN     the bar's HTTP API password, if its Wi-Fi API asks for one;
                      with --cloud, a BUSY Cloud token with the "BUSY Bar" scope

The calendar is polled every 5 minutes. A 401 or 404 from it stops the app
with an error rather than retrying. Drawings go in at priority 91, above a
running BUSY session (90), the way the bar's own calendar events do; between
events nothing is drawn, so the bar is never held.
"""

# First of all: Ctrl-C before the app is up ends it quietly. The first start
# after an install can take seconds while the system checks the newly installed
# libraries; once running, every mode handles SIGINT itself and clears the bar.
import signal
import sys

signal.signal(signal.SIGINT, lambda *_: sys.exit(0))

import argparse
import asyncio
import os
from pathlib import Path

# The app's code lives in src/busybar_calendar, next to this file.
sys.path.insert(0, str(Path(__file__).resolve().parent / "src"))

from busybar_calendar import cli, playback
from busybar_calendar.config import Config, ConfigError, find, load

APP = "busybar-calendar"
USB_HOST = "10.0.4.20"


def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
    p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    p.add_argument("--host", help=f"the bar: ip[:port] (default {USB_HOST}, USB)")
    p.add_argument("--cloud", action="store_true", help="reach the bar through BUSY Cloud")
    p.add_argument("--ics", action="append", default=[], metavar="URL", help="an ICS feed")
    p.add_argument("--caldav", metavar="URL", help="a CalDAV server or calendar URL")
    p.add_argument("--user", help="CalDAV username, usually the email address")
    p.add_argument(
        "--include",
        action="append",
        default=[],
        metavar="NAME_OR_ID",
        help="use only these CalDAV calendars (* wildcards)",
    )
    p.add_argument(
        "--exclude",
        action="append",
        default=[],
        metavar="NAME_OR_ID",
        help="leave these CalDAV calendars out",
    )
    p.add_argument("--minutes", type=int, default=5, help="reminder before an event (5)")
    p.add_argument("--priority", type=int, default=91, help="draw priority (91)")
    p.add_argument("--quiet", action="store_true", help="no sounds")
    p.add_argument("--config", help="a TOML file with every setting")
    p.add_argument("--demo", action="store_true", help="loop a made-up schedule")
    p.add_argument("--test", action="store_true", help="draw one frame and exit")
    p.add_argument("-v", "--verbose", action="store_true")
    return p.parse_args(argv)


def config_file(args: argparse.Namespace) -> Path | None:
    """The config to use: --config, else - unless calendars are given as flags - the one
    `busybar-calendar init` wrote ($BUSYBAR_CALENDAR_CONFIG, ./config.toml or
    ~/.config/busybar-calendar/config.toml), else none."""
    if args.config:
        return Path(args.config)
    if args.ics or args.caldav:
        return None
    try:
        return find()
    except ConfigError:
        return None


def build_config(args: argparse.Namespace, path: Path | None) -> Config:
    if path is not None:
        config = load(path)
        if args.host:
            config.bar.address = args.host
        return config

    bar: dict = {"application_name": APP, "priority": args.priority}
    if not args.cloud:
        bar["address"] = args.host or USB_HOST
    if os.environ.get("BUSYBAR_TOKEN"):
        bar["token_env"] = "BUSYBAR_TOKEN"
    elif args.cloud:
        raise ConfigError("--cloud needs a BUSY Cloud token in BUSYBAR_TOKEN")

    sources = [
        {"name": f"ics-{n}" if len(args.ics) > 1 else "ics", "type": "ics", "url": url}
        for n, url in enumerate(args.ics, 1)
    ]
    if args.caldav:
        caldav = {
            "name": "caldav",
            "type": "caldav",
            "url": args.caldav,
            "include": args.include,
            "exclude": args.exclude,
        }
        if args.user:
            caldav |= {"username": args.user, "password_env": "CALDAV_PASSWORD"}
        sources.append(caldav)

    sound = not args.quiet
    # --minutes 0 fails here, not at the first event
    return Config.model_validate(
        {
            "bar": bar,
            "defaults": {
                "reminder": {"minutes_before": args.minutes, "sound": sound},
                "status": {"sound": sound},
            },
            "sources": sources,
        }
    )


def main(argv: list[str] | None = None) -> int:
    args = parse_args(argv)
    cli.setup_logging(args.verbose)
    try:
        path = config_file(args)
        config = build_config(args, path)
        if args.test:
            return asyncio.run(playback.draw_test_frame(config))
        if args.demo or not config.sources:
            if not args.demo:
                print(
                    "No calendar yet (--ics, --caldav, or a config from `busybar-calendar "
                    "init`): playing a demo schedule.",
                    file=sys.stderr,
                )
            return asyncio.run(playback.run_demo(config))
        where = config.bar.address or "BUSY Cloud"
        print(
            f"{APP} -> {where}{f', config {path}' if path else ''}  (Ctrl-C to stop)",
            file=sys.stderr,
        )
        return asyncio.run(cli.run_service(config))
    except cli.EXPECTED as error:
        for line in cli.describe(error):
            print(f"{APP}: {line}", file=sys.stderr)
        return 2


if __name__ == "__main__":
    sys.exit(main())

# An example busybar-calendar config. `busybar-calendar init` writes one for you;
# every option, with its default, is in docs/configuration.md.

[bar]
# Leave out `address` to reach the bar through BUSY Cloud, with a token that has
# the "BUSY Bar" access scope. On your network: address = "192.168.1.50" and the
# bar's HTTP API password as the token.
token_command = ["security", "find-generic-password", "-s", "busybar-calendar-bar", "-w"]

[defaults.reminder]
minutes_before = 5

[defaults.status]
# Events you marked tentative ("maybe") show as busy too; false keeps only
# their reminder. They are drawn in yellow; [display] tentative_yellow = false
# turns that off.
tentative = true

# A CalDAV account: iCloud, Fastmail, Nextcloud, PrivateEmail, Radicale, ...
[[sources]]
name = "iCloud"
type = "caldav"
url = "https://caldav.icloud.com"
username = "me@icloud.com"
password_command = ["security", "find-generic-password", "-s", "busybar-calendar-icloud", "-w"]
# Which calendars: names or ids from `busybar-calendar calendars`, * wildcards.
include = ["Home", "Work"]

# One calendar shown as the bar's own "meeting" status, with an earlier reminder.
[sources.calendars.Work.reminder]
minutes_before = 10

[sources.calendars.Work.status]
show = "meeting"

# A published ICS / webcal link: Outlook's "Publish a calendar", Google's secret
# address in iCal format, a Proton share link.
[[sources]]
name = "Team"
type = "ics"
url = "webcal://outlook.office365.com/owa/calendar/.../calendar.ics"

[sources.reminder]
sound = false

# Settings by event title, from any calendar, on top of the calendar's own.
# `*` and `?` are wildcards; case does not matter.
[[titles]]
match = ["Focus time", "Commute*"]
reminder.enabled = false
status.enabled = false

[[titles]]
match = "Lunch*"
status.show = "lunch"

# Configuration reference

The config is a TOML file. `busybar-calendar init` writes one; it is found
in `~/.config/busybar-calendar/config.toml`, `./config.toml`, or wherever
`$BUSYBAR_CALENDAR_CONFIG` or `-c` points. Only `[[sources]]` is required;
everything else has the default shown.

Secrets - `token` and `password` - take one of three forms. Prefer the last
two, which keep the secret out of the file:

```toml
password = "..."                                  # inline
password_env = "CALDAV_PASSWORD"                  # an environment variable
password_command = ["security", "find-generic-password", "-s", "my-calendar", "-w"]
```

The command is run without a shell, and its output is the secret.

*Generated from the code by `python -m busybar_calendar.reference`; edit the
descriptions in `config.py`, not this file.*

## `[bar]`

How to reach the bar.

| Key | Default | |
| --- | --- | --- |
| `address` | none | The bar on your network (`ip[:port]`; `10.0.4.20` over USB). Leave it out to reach the bar through BUSY Cloud. |
| `token` / `token_env` / `token_command` | none | With an address, the bar's HTTP API password (32 characters at most); without, a BUSY Cloud token with the "BUSY Bar" access scope. |
| `priority` | `91` | Draw priority: 91 is above a running BUSY session (90), like the bar's own calendar events. |
| `application_name` | `"busybar-calendar"` | The name drawings are made under; also the app's id in the community gallery. |

## `[sync]`

How the calendars are read.

| Key | Default | |
| --- | --- | --- |
| `poll_minutes` | `5` | How often calendars are read. |
| `lookahead_hours` | `24` | How far ahead events are read. |
| `skip_free` | `true` | Leave out events marked free (`TRANSP:TRANSPARENT`). |
| `timezone` | none | For event times that carry no timezone, e.g. `Europe/Kyiv`. Default: this machine's. |

## `[display]`

What the bar shows.

| Key | Default | |
| --- | --- | --- |
| `title_font` | `"small"` | `small` fits the title and countdown on two lines; `global` draws Cyrillic, CJK and accents, on one line beside the countdown. |
| `transliterate` | `true` | Fold titles to ASCII for the bitmap fonts (`Планування` -> `Planuvannya`). Not used with `global`. |
| `reminder_sound` | `"shared/sounds/calendar_reminder_ends.snd"` | The stock sound a reminder plays. |
| `event_sound` | `"shared/sounds/calendar_event_starts.snd"` | The stock sound an event's start plays. |
| `reminder_icon` | `"red_calendar"` | The icon before an event: the red calendar, or the bar's own animation. |
| `event_icon` | `"red_calendar"` | The icon during an event: the red calendar, or the bar's own animation. |
| `busy_label` | `"BUSY"` | The word beside the countdown during an event; `""` for none. Not drawn with the `global` font. |
| `busy_color` | `"#FF0000FF"` | Its colour, `#RRGGBB` or `#RRGGBBAA`. |
| `tentative_yellow` | `true` | Draw events you marked tentative in yellow - the calendar icon and the label - so they differ from accepted ones. Off, they look the same. The icon is yellow only as the `red_calendar`; the bar's own animation has no yellow version. |

## `[defaults.reminder]`

The countdown before an event: the settings the bar's Google Calendar integration has per calendar. They layer: `[defaults.reminder]`, then a source's `[sources.reminder]`, then one calendar's `[sources.calendars."<name or id>".reminder]`, then the `[[titles]]` rules that match the event's title.

| Key | Default | |
| --- | --- | --- |
| `enabled` | `true` | Show a reminder before events. |
| `minutes_before` | `5` | How long before the start it appears. |
| `sound` | `true` | Play the reminder sound as it appears. |
| `show_name` | `true` | Show the event's title; off, it says "Next event". |

## `[defaults.status]`

What the bar shows while an event is on. It layers the same way: `[defaults.status]`, `[sources.status]`, `[sources.calendars."<name or id>".status]`, `[[titles]]`.

| Key | Default | |
| --- | --- | --- |
| `enabled` | `true` | Show the event while it is on. |
| `show` | `"name"` | `name`: the red calendar, the title, a countdown and BUSY. Or one of the bar's own statuses: `back_soon`, `booked`, `chill_time`, `coding`, `dnd`, `flow`, `keep_out`, `low_social_battery`, `lunch`, `meeting`, `on_air`, `on_call`. |
| `sound` | `true` | Play the event sound as it starts. |
| `tentative` | `true` | Events you marked tentative show as busy too. Off, they keep their reminder only. |

## `[[sources]]`

One CalDAV account or one ICS link each; at least one.

| Key | Default | |
| --- | --- | --- |
| `name` | **required** | What logs and overrides call this source; unique. |
| `type` | **required** | `caldav` for an account, `ics` for a published link (one calendar). |
| `url` | **required** | CalDAV: the server, or one calendar's URL. ICS: the link; `webcal://` works. |
| `username` | none | Usually the email address. |
| `password` / `password_env` / `password_command` | none | iCloud and Fastmail need an app password. |
| `auth` | `"basic"` | HTTP authentication; a few servers want `digest`. |
| `emails` | `[]` | Your attendee address(es), to read your response to invitations. Default: the username, when it is an email address. |
| `include` | `[]` | CalDAV: only these calendars, by name, id or URL; `*` and `?` are wildcards. Default: all. The one listed last wins an overlap. |
| `exclude` | `[]` | CalDAV: leave these calendars out, after include. |
| `calendars` | `{}` | Per-calendar reminder and status overrides, keyed by name or id. |

## `[[titles]]`

Settings for the events whose title matches, from whichever calendar: a
rule's `reminder` and `status` go on top of the calendar's, and a later rule
on top of an earlier one. To keep some events off the bar, and show lunch as
the bar's own status:

```toml
[[titles]]
match = ["Focus time", "Commute*"]
reminder.enabled = false
status.enabled = false

[[titles]]
match = "Lunch*"
reminder.enabled = false
status.show = "lunch"
```

`busybar-calendar upcoming` shows what each event ends up with.

| Key | Default | |
| --- | --- | --- |
| `match` | **required** | The titles it applies to: one or a list; `*` and `?` are wildcards, and case does not matter. |

# How it works

## Why a service, and not an app on the bar

The bar's Google Calendar integration lives in BUSY Cloud, which is not
open source. Reading the firmware shows how it reaches the bar: the cloud
sends ordinary HTTP API requests through an MQTT proxy on the device
(`mqtt_http_proxy.c`). There is no calendar endpoint, on the bar or in the
cloud's device API. A Google event on the bar is made of the same requests
anyone can send:

- `POST /api/display/draw` with the stock calendar animations, a text and a
  countdown element;
- `POST /api/audio/play` with the stock calendar sounds;
- `DELETE /api/display/draw` when it is over.

So anything that makes those requests gets the same events on screen. This
service does that, with a CalDAV account or an ICS feed in place of Google.

A JavaScript app on the bar cannot do the same thing. The firmware runs one
JS app at a time and stops it when you leave it, so it could not put a
reminder on top of a BUSY session or the clock the way the integration does.

```
 CalDAV server ─┐
 ICS feed ──────┤   busybar-calendar                         BUSY Bar
                ├─► sources ─► schedule ─► render ─► runner ─► HTTP API
 (poll)         │   (events)   (what now)  (elements) (draw,    via BUSY Cloud
                                                        clear,  (Bearer token)
                                                        sound)  or the LAN
                                                                (X-API-Token)
```

## The pieces

| Module | Does |
| --- | --- |
| `caldav.py` | Discovery (`/.well-known/caldav`, `current-user-principal`, `calendar-home-set`) and `calendar-query` REPORTs with a time range. Hrefs are joined against the URL that answered, which is what makes iCloud's per-account hosts work. |
| `sources.py` | One class per source type. CalDAV calendars are listed again every 12 refreshes; ICS feeds use `If-None-Match`. |
| `events.py` | iCalendar to events: recurrence expanded with `recurring-ical-events`, times made timezone-aware, and the filters applied. |
| `schedule.py` | Pure logic: which screen is due now, and when that next changes. |
| `render.py` | The display elements for a screen, and its sound. |
| `runner.py` | The loop: refresh, decide, draw or clear, sleep until the next change. |
| `icons.py` | The red and yellow calendars, as XPM2 images drawn inline. |
| `config.py` | The TOML config, its models and where it is found; each option's description lives here. |
| `connect.py` | What every command shares: the bar client, the sources, stopping on a signal. |
| `diagnose.py` | `check` and `status`, as text or JSON. |
| `playback.py` | Showing events outside the schedule: `replay`, the demo, the gallery's test frame. |
| `wizard.py` | `init` and `add`: the questions, the secrets, the config they write. |
| `service.py` | `install`, `uninstall`, the service's state and log: launchd or systemd. |
| `reference.py` | Generates the configuration reference from `config.py`. |
| `cli.py` | The command line: the commands, their options, which code each runs. |

## Rules

Each event can open two screens. A **reminder** runs from `minutes_before`
until the start, and a **status** runs from the start to the end.

- When several screens are due at once:
  1. **your response decides first**: an event you accepted beats one you
     marked tentative, which beats one you have not answered. Events of
     your own, with no attendees, count as accepted. Your response is your
     own attendee entry's `PARTSTAT`, found by your address (`emails`, which
     defaults to the CalDAV username), and it counts even on events you
     organise. Published feeds leave the attendees out; there the event's
     own marking counts instead, Outlook's `X-MICROSOFT-CDO-BUSYSTATUS:TENTATIVE`
     or `STATUS:TENTATIVE`;
  2. then the event starting latest, the Google integration's rule ("the
     newest event and the most recently added calendar take priority"), so
     a reminder for your next meeting replaces the status of the one still
     running, as long as you are as sure to attend the next one;
  3. then the calendar configured last.
- The response ranks whole screens, so it holds however two events are
  placed against each other. With Maybe 10:00-11:00 and Sure 10:30-11:30
  the bar shows Maybe, then Sure from its reminder at 10:25 until it
  ends at 11:30 - Maybe's end at 11:00 changes nothing. With Sure
  10:00-11:00 and Maybe 10:30-11:30, Maybe's reminder and start do not
  cut in, and Maybe appears when Sure ends. A tentative event never takes
  the bar from an accepted one that is showing something.
- An event you marked tentative puts the busy status up like any other,
  unless `status.tentative = false`: then it keeps its reminder but never
  shows as busy, and whatever else is on carries on.
- A tentative event is also drawn differently: a yellow calendar and a yellow
  `BUSY`, in its reminder and its status alike, where an accepted or
  unanswered one gets the red ones. `display.tentative_yellow = false`
  draws them all in red. A calendar icon set to the bar's own `animation`
  stays as it is (the stock animation has no yellow version) and only the
  label turns yellow, and a stock status such as `meeting` is never recoloured.
  Changing your answer on your phone redraws the screen at the next refresh.
- Like Google: events of 24 hours or more, and all-day events, are not
  shown.
- Also skipped: `STATUS:CANCELLED`, `TRANSP:TRANSPARENT` (free) unless
  `skip_free = false`, and invitations you declined or delegated.
- A sound plays when a screen opens, but not when the service starts in
  the middle of one: restarting during a meeting does not chime again.

## Drawing

| Element | Reminder | Status (`show = "name"`) | Status (`show = "meeting"` etc.) |
| --- | --- | --- | --- |
| `cal_xpm` | the red calendar (default) | the red calendar (default) | |
| `cal_xpm_maybe` | the yellow calendar, for a tentative event | the yellow calendar, for a tentative event | |
| `cal_icon` | `shared/animations/calendar_reminder_16x16.anim` with `reminder_icon = "animation"` | `shared/animations/calendar_event_16x16.anim` with `event_icon = "animation"` | |
| `cal_title` | title, `small` font, scrolls if long | title | |
| `cal_time` | countdown to the start | countdown to the end | |
| `cal_busy` | | `BUSY` in red (yellow for a tentative event), right-aligned on the countdown's line | |
| `cal_status` | | | `shared/animations/<status>_72x16.anim` |

The calendar travels inside each drawing as an XPM2 `xpmbitmap`
element (the firmware takes up to 32 colours, full colour on the front
display), so nothing is uploaded to the bar. busylib 2.6 has no model for
that element, so drawings are posted with `api_request` rather than
`display_draw`. The icons are redrawn from Noto Emoji's 📅 at 16x16; see
`icons.py` for the pixels and their licence. The yellow one has an element id of its own
(`cal_xpm_maybe`), so a switch between the colours clears and redraws the
icon instead of depending on the bar swapping an existing bitmap's pixels.

Sounds: `shared/sounds/calendar_reminder_ends.snd` when a reminder opens and
`shared/sounds/calendar_event_starts.snd` when an event starts. Both can be
changed under `[display]`.

Drawings go in at priority 91. The firmware uses 10 for its built-in apps
and 90 for an active BUSY session, so like Google events these appear above
a running session. Every element carries `display_until`, so the bar takes
the drawing down by itself if the service stops.

## Measured on the hardware

The layout and timing were checked on a bar running firmware 1.2.4 / API
27.5.0, by drawing each screen and reading the pixels back with
`GET /api/screen` (the source of the pictures in the README). That turned
up things the API description does not say:

- **The countdown sits high in its box.** Countdown elements use the 7px
  `superscript` font, which puts its digits 4px above the bottom of the
  element. Anchored `bottom_left` at y=16, the digits landed on rows 7-11,
  into the title's descenders. At y=19 they land on rows 10-14, level with
  the icon's last row. Beside a `global`-font title, the countdown sits at
  y=9 so both share rows 6-10.
- **A redraw at the moment of expiry loses its animation.** Redrawing an
  element at the same instant its old `display_until` fires drops the
  animated icon (0 of 256 icon pixels lit). With the old expiry even a few
  seconds later, the redraw keeps it. So `display_until` is the screen's
  end plus 60 seconds: the service redraws or clears on time anyway, and
  the extra minute only matters if it has stopped.
- **A draw merges by element id.** It updates the ids it names and leaves
  the others up, so drawing the `meeting` animation after a reminder would
  leave the reminder's elements underneath. The service clears its own
  drawing first only when an element would be left over, and otherwise
  updates in place. A reminder turning into its event only adds BUSY, so
  that change is seamless: sampling the screen across it, clearing first
  caught a half-drawn icon (96 of 234 pixels lit) in 1 of 20 frames, and
  updating in place showed the full icon in all 20.
- **The screen has one owner.** `DELETE /api/display/draw` with this
  application's name, while another application is on screen, answers
  `400 this application_name is currently not displaying anything`. The
  service takes that as "already clear" rather than an error to retry.
- **Text is not ASCII-only.** The published schema limits `text` to
  printable ASCII, but the firmware accepts any text, and the `global` font
  (Lana Pixel 11) draws Cyrillic. The default stays the schema-conforming
  `small` font with transliteration; `title_font = "global"` is opt-in.
- **LAN tokens are 32 characters at most**, and over Wi-Fi nothing but
  `/api/version`, `/api/access` and `/api/transport` answers while the
  HTTP API is disabled.
- Through BUSY Cloud, a reminder, its start and its end each reached the
  bar within half a second of the event's time.

## Limits

- Changes are seen on the next poll (`poll_minutes`, default 5), and ICS
  feeds are only as fresh as their publisher makes them.
- Only the front display is drawn on.
- The bar's own clock decides `display_until` and the countdowns. It keeps
  network time, so this matters only if its clock is off.

# Setup

The quick way:

```sh
uv tool install git+https://github.com/kurok/busybar-calendar
busybar-calendar init      # answers in, config out: the bar, the calendar, the passwords
busybar-calendar check     # proves it works, or says what to fix
busybar-calendar install   # runs it in the background from now on
busybar-calendar status    # and later: is it running, and what is on the bar next
```

The rest of this page is what those commands do for you, for when you
want to do it yourself, or need more than one calendar source. Every option
of the config is in the [configuration reference](configuration.md).

1. [Connect to the bar](#connect-to-the-bar)
2. [Add your calendars](#add-your-calendars)
3. [Keep secrets out of files](#keep-secrets-out-of-files)
4. [Check it](#check-it)
5. [Run it as a service](#run-it-as-a-service)
6. [Troubleshooting](troubleshooting.md)

## Connect to the bar

There are two ways to reach the bar. They draw exactly the same things.

### Through BUSY Cloud (simplest)

This is the route the bar's Google Calendar integration takes, and it works
from anywhere, with nothing to enable on the bar.

1. In your BUSY account, create an API token and choose **BUSY Bar** under
   **Access scope**.
2. Store it (see [secrets](#keep-secrets-out-of-files)) and give it to
   `[bar]` without an `address`:

```toml
[bar]
token_command = ["security", "find-generic-password", "-s", "busybar-token", "-w"]
```

It is sent as `Authorization: Bearer ...` to `https://api.busy.app/busybar`.

### On the local network

Faster, and does not depend on the cloud, but the bar's HTTP API over Wi-Fi
is **disabled by default**.

1. Connect the bar to your computer by USB and open `http://10.0.4.20`.
2. On the **Network** tab, in **HTTP API**, choose **Set password and
   enable**. Keep the password to **32 characters or fewer**. The firmware
   refuses longer ones.
3. Find the bar's address: **Settings -> Wi-Fi -> your network -> View IP
   Address**.

```toml
[bar]
address = "192.168.1.50"
token_command = ["security", "find-generic-password", "-s", "busybar-lan", "-w"]
```

The password is sent as `X-API-Token`. To check the bar's mode without a
password: `curl http://<address>/api/access` returns `{"mode":"disabled"}`,
`"enabled"` or `"key"`. While it says `disabled`, every other request over
Wi-Fi gets `403 Forbidden`, whatever token you send. Over USB
(`address = "10.0.4.20"`) no password is needed at all.

## Add your calendars

Each `[[sources]]` entry is one CalDAV account or one ICS feed. A CalDAV
account uses all of its calendars unless you [filter them](#choosing-calendars).

`busybar-calendar add` adds one more by asking the same questions as `init`,
and appends it to your config without touching the rest, then restarts a
background service so it reads the new calendar at once.

A running service also follows edits you make by hand: they apply within a
minute. An edit that does not load leaves it on the config it has, and its
log says what is wrong; a change under `[bar]` waits for
`busybar-calendar restart`.

### CalDAV

| Provider | `url` | Password |
| --- | --- | --- |
| iCloud | `https://caldav.icloud.com` | an app-specific password (account.apple.com -> Sign-In and Security -> App-Specific Passwords) |
| Fastmail | `https://caldav.fastmail.com` | an app password (Settings -> Privacy & Security) |
| Nextcloud | `https://cloud.example.com/remote.php/dav` | your password, or an app password |
| PrivateEmail (Namecheap) | `https://dav.privateemail.com` | your mailbox password |
| Radicale, Baïkal, Synology, others | the server's root URL, or a calendar's URL | as the server wants it |

`username` is usually your full email address. A root URL is enough when
the server supports discovery (`/.well-known/caldav`); otherwise give the
URL of one calendar, and it is used as it is. Servers that only speak
Digest auth need `auth = "digest"`.

```toml
[[sources]]
name = "iCloud"
type = "caldav"
url = "https://caldav.icloud.com"
username = "me@icloud.com"
password_command = ["security", "find-generic-password", "-s", "busybar-icloud", "-w"]
include = ["Home", "Work"]

[sources.calendars.Work.status]
show = "meeting"
```

### Choosing calendars

`busybar-calendar calendars` lists each calendar on the account with its
**id** (the last part of its URL) and **name**, and marks the ones in use:

```
PrivateEmail (caldav): 22 calendars, 1 used
  * 4711   Doe, Jane
    5001   Ops Maintenances
    5002   Infra Maintenances
    6001   Office - Room 1 (6 people)
    ...
```

Two lists filter them. Each entry is a calendar's **name**, its **id**, or
its **URL**, and may use the wildcards `*` and `?`. Matching is exact and
case-sensitive.

| | |
| --- | --- |
| `include` | Use only these calendars. Without it, all of them. |
| `exclude` | Leave these out, after `include`. |

```toml
include = ["Doe, Jane"]                 # by name
include = ["4711"]                     # by id: survives a rename
include = ["Doe, Jane", "* Maintenances"]
exclude = ["Office - Room *", "Room *"]   # everything except the meeting rooms
```

Organisation accounts often expose shared calendars. A PrivateEmail
business mailbox, for example, lists every meeting room and team calendar
next to your own. With no filter, other people's room bookings would reach
your bar, so name your own calendar under `include`.

Calendars come in the order `include` lists them: when two events start at
the same time, the calendar listed last wins. An entry that matches nothing
is reported, by `calendars` and in the service's log.

Per-calendar settings can be keyed by name or by id, and the id wins when
both are given:

```toml
[sources.calendars."4711".reminder]
minutes_before = 10
```

Your answer to each invitation is read from your attendee entry, found by
your address: declined invitations are skipped, and when two events overlap,
the one you accepted wins over one you marked tentative or have not
answered - whether they start together or one is shifted against the other.
An event you marked tentative ("Maybe") is drawn with a yellow calendar and
a yellow BUSY instead of the red ones. The address defaults to `username` when that is an email address;
set `emails = [...]` if your invitations go to another one.

### ICS / webcal feeds

For calendars that only publish a link. A feed is one calendar, named after
its source. `webcal://` links work as they are.

| Calendar | Where to find the link |
| --- | --- |
| Outlook / Microsoft 365 | Settings -> Calendar -> Shared calendars -> **Publish a calendar** -> ICS link |
| Google Calendar | Settings -> the calendar -> Integrate calendar -> **Secret address in iCal format** |
| Proton Calendar | the calendar's menu -> Share -> **Share with anyone** (link) |

```toml
[[sources]]
name = "Outlook"
type = "ics"
url = "https://outlook.office365.com/owa/calendar/.../calendar.ics"
```

A published feed leaves out who is invited, so your own answer to an invitation
is not in it; an event the feed marks tentative (Outlook does, as its busy
status) still counts as tentative. Outlook's Windows timezone names are
understood. A feed is only as fresh as the provider makes it. Outlook and Google can
take a while to republish a change, while CalDAV sees it on the next poll
(`poll_minutes`, default 5).

## Keep secrets out of files

Every password and token takes one of three forms. Prefer the last two:

```toml
password = "..."                       # inline: only for throwaway testing
password_env = "ICLOUD_APP_PASSWORD"   # an environment variable
password_command = ["security", "find-generic-password", "-s", "busybar-icloud", "-w"]
```

The same goes for the bar: `token`, `token_env`, `token_command`. A command
is run without a shell and its output, stripped, is the secret.

On macOS, store a secret in the Keychain from your own terminal. It prompts,
so the secret ends up neither on screen nor in your shell history:

```sh
security add-generic-password -U -s busybar-icloud -a me@icloud.com -w
```

On Linux, `secret-tool` (libsecret) or `pass` work the same way:
`password_command = ["secret-tool", "lookup", "service", "busybar-icloud"]`.

`config.toml` is in `.gitignore`. Keep it that way even with no secrets in
it, since it names your accounts.

## Check it

```sh
busybar-calendar check
```

checks the whole setup and says what to fix:

```
Bar
  ok   BUSY Cloud: firmware 1.2.4, API 27.5.0, token accepted
Calendars
  ok   iCloud: signed in; 2 of 5 calendars used: Home, Work
  ok   iCloud: 23 events in the next 7 days; next Tue 13 Oct 09:00 Standup

All good.
```

A refused bar call comes with its cause: the Wi-Fi HTTP API switched off,
a missing password, or a cloud token given as a LAN password. The other
commands look closer:

```sh
busybar-calendar calendars                 # discovery: calendars per CalDAV source
busybar-calendar upcoming --hours 48       # events, settings, your response, what is on now
busybar-calendar demo                      # a sample reminder for 20 seconds
busybar-calendar demo --status --show meeting
busybar-calendar demo --font global --title "Планування спринту"
busybar-calendar replay                    # tomorrow's real events, one a minute
busybar-calendar replay --day today --seconds 30 --quiet
busybar-calendar -v run                    # run in the foreground with debug logs
```

## Run it as a service

```sh
busybar-calendar install
```

checks the setup, then makes it run in the background from now on: at
login, and again if it stops. On macOS that is a launch agent
(`~/Library/LaunchAgents/app.busybar.calendar.plist`, logging to
`~/Library/Logs/busybar-calendar.log`); on Linux a systemd user unit
(`~/.config/systemd/user/busybar-calendar.service`, logs in
`journalctl --user -u busybar-calendar`).

- It runs from the environment you installed from (a `uv tool` or a
  virtualenv) and reads the config `install` found, wherever you start it.
- Restarts are five minutes apart, so a calendar that refuses your password
  is not asked again every few seconds.
- A launch agent runs in your login session, so it can read the login
  Keychain for `token_command` / `password_command`.
- `--dry-run` shows the file and the commands without changing anything;
  `--force` installs even when `check` finds a problem.
- `--auto-update` makes it [update itself](#updating-by-itself) every time
  it starts.
- `busybar-calendar uninstall` stops and removes it.

`busybar-calendar status` shows how it is doing:

```
busybar-calendar 0.3.1
Service   running 0.3.1, pid 4321
          log /Users/me/Library/Logs/busybar-calendar.log
            16:40:19 INFO busybar_calendar.runner: reminder: Design review (Work, accepted) ...
            16:45:00 INFO busybar_calendar.runner: status: Design review (Work, accepted) ...
Bar       BUSY Cloud: answering
Calendar  now status: Design review, until Tue 13 Oct 17:30 (in 44m)
          next reminder: Retro, at Tue 13 Oct 17:55 (in 1h 09m)
```

A stopped service shows its last exit code, with the log lines that explain it.

Both `status` and `check` take `--json`, for scripts, dashboards or a menu-bar
widget. `check --json` exits non-zero when something fails, like `check`:

```sh
busybar-calendar status --json | jq -r '.calendar.next | "\(.kind) \(.title) at \(.at)"'
busybar-calendar check --json | jq '.findings[] | select(.ok | not) | .message'
```

### Upgrading

Upgrade the install, then restart the service, which keeps running the old
version until then:

```sh
uv tool upgrade busybar-calendar   # fetches the newest from git, for the command and the service
busybar-calendar restart
```

That works for the one-line install from git. An install from a clone takes
`git pull && uv tool install --force .`, and one from a release file or a
tag (`...@v0.3.1`) takes `uv tool install --force` with the new one. Your
config and passwords stay where they are.

`status` shows which version the service runs, and says when it is not the
one just installed:

```
Service   running 0.3.0, pid 4321
          that is 0.3.0, but this is 0.3.1: `busybar-calendar restart` runs this one
```

When the command you run is from another install than the service (a
checkout run with `uv run`, say), a restart would start the old version
again, so `status` names the install to upgrade instead:

```
          that is 0.3.0, from ~/.local/share/uv/tools/busybar-calendar, not this 0.3.1:
          `uv tool upgrade busybar-calendar`, then `busybar-calendar restart`
```

It gives the `uv tool upgrade` command when that install is a uv tool from
git, and says "upgrade that one" otherwise.

#### Updating by itself

```sh
busybar-calendar install --auto-update
```

installs the service so that every start - at login, after a restart, or
after it stopped - first runs `uv tool upgrade busybar-calendar`, then
starts the newest version. It comes before the config is read, so a config
that uses something new gets the version that understands it.

- It needs the one-line install from git (`uv tool install
  git+https://github.com/kurok/busybar-calendar`): that is the install
  `uv tool upgrade` moves forward, to the newest commit on `main`. `install`
  refuses `--auto-update` for any other install, and when there is no `uv`.
- If the update fails - no network yet at login, say - the service starts
  the version it has, and tries again at its next start. Each start logs
  what happened:

  ```
  INFO busybar_calendar.update: auto-update: 0.5.1 (a0c7935) -> 0.6.1 (0046d3c)
  INFO busybar_calendar: busybar-calendar 0.6.1 started: 1 calendar source(s), bar via BUSY Cloud
  ```

- So `busybar-calendar restart` is also how to update now, and `status`
  says so: `Service   running 0.6.1, pid 4321, updates itself at each start`.
- `install` without the flag turns it off again.

### Docker

```sh
docker build -t busybar-calendar .
docker run -d --restart unless-stopped \
  -e BUSYBAR_TOKEN -e CALDAV_PASSWORD \
  -v "$PWD/config.toml:/config/config.toml:ro" busybar-calendar
```

In a container, use `token_env` and `password_env`, since the Keychain is
not there.

## Troubleshooting

See [troubleshooting.md](troubleshooting.md): what `check` and `status` say
for each common problem, and what to do about it.

# Troubleshooting

Two commands answer most questions:

```sh
busybar-calendar check    # is the setup right? the bar, its token, every calendar
busybar-calendar status   # is the service running, what did it last log, what is on the bar?
```

The outputs below are the commands' own, from real failures.

## The bar refuses: `refused (403)`

`check` names the cause after the code.

**The bar's HTTP API is off over Wi-Fi.** It is off until you switch it on:

```
Bar
  FAIL 192.168.1.50: refused (403). The bar's HTTP API over Wi-Fi is disabled: enable it at http://10.0.4.20 (USB) -> Network -> HTTP API, or use a BUSY Cloud token without an address.
```

Connect the bar by USB, open `http://10.0.4.20`, then **Network -> HTTP API
-> Set password and enable**. Or leave `address` out of `[bar]` and give a
BUSY Cloud token instead: that needs nothing switched on.

**The cloud token is wrong, revoked, or lacks the scope:**

```
Bar
  FAIL BUSY Cloud: refused (403). The cloud token is wrong, revoked, or lacks the BUSY Bar access scope.
```

Create a new token in your BUSY account with **BUSY Bar** under **Access
scope**, and store it where `token_command` / `token_env` reads it.

**A cloud token given as the bar's password.** With `address` set, the token
must be the HTTP API password, 32 characters at most; `check` spots a cloud
token by its length (`The token is 43 characters ... Is it a cloud token?`).
Leave `address` out to use the cloud token as one.

## The bar is unreachable

```
  FAIL 192.168.1.50: unreachable (...)
```

The address is wrong, or the bar is off or on another network: the computer
must be on the bar's network for a LAN address (**Settings -> Wi-Fi -> your
network -> View IP Address** on the bar). Over USB the bar is always
`10.0.4.20`. BUSY Cloud works from anywhere.

## The bar stopped answering

`status` checks the bar too:

```
Bar       BUSY Cloud: NOT answering (no answer). Is it on and online? If it stays stuck, unplug it and plug it back in.
```

A bar that answers ping but not its HTTP API - not on the LAN, not through
BUSY Cloud - has a stuck HTTP server; the service cannot draw until it is
power-cycled, and carries on by itself once the bar is back. (Seen on
firmware 1.2.4 after a draw request with a title of thousands of
characters; the service now caps titles at 120.)

## A calendar refuses the password

```
Calendars
  FAIL iCloud: PROPFIND https://caldav.icloud.com/: 401, check the credentials
```

iCloud and Fastmail need an **app password**, not the account's own. Store
the new one under the same Keychain entry, then restart the service, which
reads passwords only when it starts:

```sh
security add-generic-password -U -s busybar-calendar-me@icloud.com -a me@icloud.com -w
busybar-calendar restart
```

A running service stops on a refused password rather than asking again and
again, and `status` shows it:

```
Service   stopped (last exit code 1); the log says why
          log /Users/me/Library/Logs/busybar-calendar.log
            busybar-calendar: iCloud: PROPFIND https://caldav.icloud.com/: 401, check the credentials
```

It is started again five minutes later, so fixing the password is enough;
`busybar-calendar restart` does not wait.

## `no calendar matches`

```
Calendars
  FAIL Work: signed in; 0 of 2 calendars used: none
  FAIL Work: no calendar matches 'Wrok'; there are: Team, Work
```

An `include` or `exclude` entry names no calendar. Names are exact and
case-sensitive; `busybar-calendar calendars` lists them with their ids, and
an id keeps working when a calendar is renamed.

## `Config does not load`

```
Config    does not load: /Users/me/.config/busybar-calendar/config.toml
          the running service keeps the config it last loaded
            titles.0.status: show: show must be 'name' or one of back_soon, booked, ...
```

An edit broke the config. The service picks up edits by itself within a
minute, but not this one: it carries on with the config it last loaded,
and its log has the same lines. Each says where the problem is -
`titles.0` is the first `[[titles]]` rule, `sources.1` the second source -
and once the file is fixed, the service takes it at its next wake.

## Nothing on the bar during a meeting

`busybar-calendar status` says what the service thinks is on the bar:

- **`nothing on the bar now`**: the event is not one it shows. `busybar-calendar
  upcoming` lists every event it will show, with your response. Events are
  left out when they are all-day or 24 hours or longer, cancelled, marked
  free (`skip_free`), declined, in a calendar that `include` / `exclude`
  leaves out, or tentative with `status.tentative = false`.
- **`now status: ...` but the bar shows something else**: something above
  `bar.priority` (91) holds the screen, such as a menu you opened on the bar.
  The calendar comes back when it lets go; the log shows `bar refused the
  update (...)` meanwhile.

## A reminder came late, or not at all

Calendars are read every `poll_minutes` (5): an event added two minutes
before it starts can miss its reminder. ICS links are only as fresh as their
publisher makes them; Outlook and Google can take hours to republish.

## Getting more detail

```sh
busybar-calendar -v run                    # the service in the foreground, with debug logs
busybar-calendar check --json              # the findings as data, to attach to a report
busybar-calendar status --json
```

name: CalDAV Calendar
author: kurok
description: Meeting reminders with a countdown, then a red BUSY while it runs, from any CalDAV or ICS calendar - iCloud, Fastmail, Nextcloud, PrivateEmail or an Outlook link.
tags:
  - calendar
  - caldav
  - ics
  - productivity
  - info
preview: ./preview.gif
repo: https://github.com/kurok/busybar-calendar

[project]
name = "busybar-calendar"
version = "0.8.0"
description = "CalDAV and ICS calendar reminders for the BUSY Bar, drawn the way its Google Calendar integration draws them"
readme = "README.md"
license = "MIT AND OFL-1.1"
license-files = ["LICENSE", "LICENSES/*"]
requires-python = ">=3.11"
dependencies = [
  "busylib>=2.6,<3",
  "httpx>=0.27",
  "icalendar>=6",
  "recurring-ical-events>=3.3",
  "defusedxml>=0.7",
  "anyascii>=0.3",
]

[project.scripts]
busybar-calendar = "busybar_calendar.cli:main"

[dependency-groups]
dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.6"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]

[tool.ruff.lint.per-file-ignores]
# Non-Latin event titles are the point of these tests.
"tests/*" = ["RUF001"]
# The SIGINT handler has to be in place before the first slow import.
"app.py" = ["E402", "I001"]

# busylib: Flipper's official BUSY Bar client (pre-approved) - LAN and BUSY Cloud.
busylib>=2.6,<3
# The calendar side, which the standard library cannot do safely or correctly:
# httpx speaks CalDAV's PROPFIND/REPORT with Basic and Digest auth,
httpx>=0.27
# icalendar parses the events and recurring-ical-events expands RRULE/EXDATE
# and moved occurrences in their own timezones,
icalendar>=6
recurring-ical-events>=3.3
# defusedxml parses the server's XML without entity expansion attacks,
defusedxml>=0.7
# anyascii turns titles in other scripts into text the bar's bitmap fonts draw.
anyascii>=0.3

"""
Regenerate the screenshots in docs/images from a real bar.

Draws each layout on the bar named in a busybar-calendar config, reads the
front display back through GET /api/screen, and saves it as LED-style PNGs,
plus GIFs for the moving ones. Sounds stay off. Needs Pillow:

    uv run --with pillow python scripts/capture_screens.py -c config.toml docs/images

With the service running, a capture takes its screen down: the drawing goes up
over whatever the service has on the bar - under another application name too,
the firmware swaps the canvas - and what it replaces does not come back by
itself, as the service only redraws at its next change. Stop the service first,
or touch its config file afterwards, which makes it redraw at once.
"""

from __future__ import annotations

import argparse
import asyncio
import contextlib
import itertools
import time
from datetime import UTC, datetime, timedelta
from pathlib import Path

from PIL import Image, ImageDraw

from busybar_calendar import render
from busybar_calendar.config import DisplayConfig, ReminderSettings, StatusSettings, load
from busybar_calendar.connect import make_bar
from busybar_calendar.events import CalendarRef, Event
from busybar_calendar.schedule import Screen

W, H = 72, 16
CELL, DOT, PAD = 10, 8, 16
BACKGROUND, UNLIT = (12, 12, 12), (28, 28, 28)


def led(rgb: bytes) -> Image.Image:
    """A front-display frame as the bar shows it: square LEDs on a dark panel."""
    image = Image.new("RGB", (W * CELL + 2 * PAD, H * CELL + 2 * PAD), BACKGROUND)
    draw = ImageDraw.Draw(image)
    for y in range(H):
        for x in range(W):
            i = (y * W + x) * 3
            colour = tuple(rgb[i : i + 3])
            if max(colour) < 20:
                colour = UNLIT
            left, top = PAD + x * CELL, PAD + y * CELL
            draw.rounded_rectangle((left, top, left + DOT, top + DOT), radius=2, fill=colour)
    return image


def scenarios(now: datetime):
    """(file name, screen, display settings, frames: 1 for a PNG, more for a GIF)."""
    ref = CalendarRef("Work", "Work", 0)

    def event(title: str, start_in: int, length: int = 30, response: str = "accepted") -> Event:
        start = now + timedelta(minutes=start_in)
        return Event("doc", title, start, start + timedelta(minutes=length), ref, response)

    reminder, status, small = ReminderSettings(), StatusSettings(), DisplayConfig()
    meeting = StatusSettings(show="meeting")
    hidden = ReminderSettings(show_name=False)
    cyrillic = event("Планування спринту", 5)
    yield "reminder", Screen("reminder", event("Design review", 5), reminder, status), small, 18
    yield "status", Screen("status", event("Design review", -2, 45), reminder, status), small, 1
    maybe = event("Design review", -2, 45, "tentative")
    yield "status-tentative", Screen("status", maybe, reminder, status), small, 1
    in_progress = event("Design review", -2, 45)
    yield "status-meeting", Screen("status", in_progress, reminder, meeting), small, 18
    long_title = event("Quarterly planning with the design team", 10)
    yield "long-title", Screen("reminder", long_title, reminder, status), small, 24
    global_font = DisplayConfig(title_font="global")
    yield "cyrillic-global", Screen("reminder", cyrillic, reminder, status), global_font, 24
    yield "cyrillic-transliterated", Screen("reminder", cyrillic, reminder, status), small, 24
    yield "hidden-name", Screen("reminder", event("Design review", 5), hidden, status), small, 1


async def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("-c", "--config", default="config.toml")
    parser.add_argument("out", type=Path)
    parser.add_argument("only", nargs="*", help="capture only these names")
    args = parser.parse_args()

    config = load(args.config)
    app = config.bar.application_name
    args.out.mkdir(parents=True, exist_ok=True)
    bar = make_bar(config)
    try:
        for name, screen, display, count in scenarios(datetime.now(UTC)):
            if args.only and name not in args.only:
                continue
            with contextlib.suppress(Exception):  # 400 when nothing of ours is up
                await bar.display_clear(application_name=app)
            await render.send(bar, render.drawing(screen, display, app, config.bar.priority))
            await asyncio.sleep(2.5)  # let the cloud deliver it and the scroll begin
            frames, stamps = [], []
            for _ in range(count):
                frames.append(led(await bar.screen(0)))
                stamps.append(time.monotonic())
            if count > 1:
                gaps = [int((b - a) * 1000) for a, b in itertools.pairwise(stamps)]
                frames[0].save(
                    args.out / f"{name}.gif",
                    save_all=True,
                    append_images=frames[1:],
                    duration=[*gaps, gaps[-1]],
                    loop=0,
                    optimize=True,
                )
            frames[len(frames) // 2].save(args.out / f"{name}.png", optimize=True)
            print(f"{name}: {count} frame(s)")
    finally:
        with contextlib.suppress(Exception):
            await bar.display_clear(application_name=app)
        await bar.aclose()


if __name__ == "__main__":
    asyncio.run(main())

"""CalDAV and ICS calendar reminders for the BUSY Bar."""

from importlib.metadata import PackageNotFoundError, version

try:
    __version__ = version("busybar-calendar")
except PackageNotFoundError:  # run from a checkout without installing, as app.py does
    __version__ = "unknown"

import sys

from .cli import main

sys.exit(main())

"""
A small, read-only CalDAV client: find the calendars, read events in a range.

Only the parts of RFC 4791 a reminder needs: discovery through
current-user-principal and calendar-home-set (RFC 5397, RFC 6764's
/.well-known/caldav as a fallback), and calendar-query REPORTs with a time
range. Recurrence is expanded by the caller, not the server.

Hrefs are joined against the URL that answered, which is what makes iCloud
work: its principal and calendars live on a per-account host, returned as
absolute URLs.
"""

from __future__ import annotations

import logging
from dataclasses import dataclass
from datetime import UTC, datetime
from urllib.parse import unquote, urljoin, urlsplit
from xml.etree.ElementTree import Element

import httpx
from defusedxml.ElementTree import fromstring

logger = logging.getLogger(__name__)

DAV = "DAV:"
CALDAV = "urn:ietf:params:xml:ns:caldav"
APPLE = "http://apple.com/ns/ical/"
NS = {"d": DAV, "c": CALDAV, "a": APPLE}

_PROPFIND_ENTRY = """<?xml version="1.0" encoding="utf-8"?>
<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
  <d:prop><d:current-user-principal/><d:resourcetype/><d:displayname/></d:prop>
</d:propfind>"""

_PROPFIND_HOME = """<?xml version="1.0" encoding="utf-8"?>
<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
  <d:prop><c:calendar-home-set/></d:prop>
</d:propfind>"""

_PROPFIND_CALENDARS = """<?xml version="1.0" encoding="utf-8"?>
<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
  <d:prop>
    <d:resourcetype/><d:displayname/><c:supported-calendar-component-set/>
  </d:prop>
</d:propfind>"""

_REPORT_RANGE = """<?xml version="1.0" encoding="utf-8"?>
<c:calendar-query xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
  <d:prop><c:calendar-data/></d:prop>
  <c:filter>
    <c:comp-filter name="VCALENDAR">
      <c:comp-filter name="VEVENT">
        <c:time-range start="{start}" end="{end}"/>
      </c:comp-filter>
    </c:comp-filter>
  </c:filter>
</c:calendar-query>"""


MAX_REDIRECTS = 5


class CalDAVError(Exception):
    def __init__(self, message: str, status: int | None = None) -> None:
        super().__init__(message)
        self.status = status


class CalDAVAuthError(CalDAVError):
    pass


@dataclass(frozen=True)
class RemoteCalendar:
    url: str
    name: str

    @property
    def id(self) -> str:
        """The calendar's own path segment: 4711 in .../calendars/me@example.com/4711/."""
        return unquote(urlsplit(self.url).path.rstrip("/").rsplit("/", 1)[-1])


@dataclass(frozen=True)
class _Response:
    href: str
    props: Element


def _stamp(value: datetime) -> str:
    return value.astimezone(UTC).strftime("%Y%m%dT%H%M%SZ")


class CalDAVClient:
    def __init__(self, http: httpx.AsyncClient, url: str) -> None:
        self._http = http
        self._url = url

    async def _send(self, method: str, url: str, body: str, depth: str) -> httpx.Response:
        """
        Send a DAV request, following redirects with the method and body intact.

        httpx, like browsers, turns a 302 into a GET; a PROPFIND that becomes
        a GET is refused. /.well-known/caldav is usually a 302 (RFC 6764).
        """
        headers = {"Depth": depth, "Content-Type": "application/xml; charset=utf-8"}
        for _ in range(MAX_REDIRECTS + 1):
            response = await self._http.request(
                method, url, content=body.encode(), headers=headers, follow_redirects=False
            )
            location = response.headers.get("Location")
            if response.status_code not in (301, 302, 303, 307, 308) or not location:
                return response
            url = urljoin(str(response.url), location)
        raise CalDAVError(f"{method} {url}: more than {MAX_REDIRECTS} redirects")

    async def _dav(self, method: str, url: str, body: str, depth: str) -> list[_Response]:
        response = await self._send(method, url, body, depth)
        code = response.status_code
        if code in (401, 403):
            raise CalDAVAuthError(f"{method} {url}: {code}, check the credentials", code)
        if code != 207:
            raise CalDAVError(f"{method} {url}: expected 207, got {code}", code)
        base = str(response.url)
        root = fromstring(response.content)
        results = []
        for item in root.findall("d:response", NS):
            href = item.findtext("d:href", default="", namespaces=NS).strip()
            for propstat in item.findall("d:propstat", NS):
                status = propstat.findtext("d:status", default="", namespaces=NS)
                prop = propstat.find("d:prop", NS)
                if " 200 " in f"{status} " and prop is not None:
                    results.append(_Response(urljoin(base, href), prop))
        return results

    async def _href(self, url: str, body: str, path: str) -> str | None:
        for response in await self._dav("PROPFIND", url, body, "0"):
            href = response.props.findtext(path, default="", namespaces=NS).strip()
            if href:
                return urljoin(response.href, href)
        return None

    async def _principal(self, url: str) -> tuple[str | None, list[_Response]]:
        try:
            entry = await self._dav("PROPFIND", url, _PROPFIND_ENTRY, "0")
        except CalDAVAuthError:
            raise
        except CalDAVError as error:
            logger.debug("%s", error)
            return None, []
        for response in entry:
            href = response.props.findtext(
                "d:current-user-principal/d:href", default="", namespaces=NS
            ).strip()
            if href:
                return urljoin(response.href, href), entry
        return None, entry

    async def discover(self) -> list[RemoteCalendar]:
        """The event calendars behind the configured URL."""
        principal, entry = await self._principal(self._url)
        # A calendar URL given directly is used as it is.
        for response in entry:
            if response.props.find("d:resourcetype/c:calendar", NS) is not None:
                name = response.props.findtext("d:displayname", default="", namespaces=NS)
                return [RemoteCalendar(response.href, name.strip() or response.href)]

        if principal is None:
            parts = urlsplit(self._url)
            well_known = f"{parts.scheme}://{parts.netloc}/.well-known/caldav"
            if self._url.rstrip("/") != well_known:
                principal, _ = await self._principal(well_known)
        if principal is None:
            raise CalDAVError(f"{self._url}: no current-user-principal; give a calendar URL")

        home = await self._href(principal, _PROPFIND_HOME, "c:calendar-home-set/d:href")
        if home is None:
            raise CalDAVError(f"{principal}: no calendar-home-set")

        calendars = []
        for response in await self._dav("PROPFIND", home, _PROPFIND_CALENDARS, "1"):
            if response.props.find("d:resourcetype/c:calendar", NS) is None:
                continue
            components = response.props.findall("c:supported-calendar-component-set/c:comp", NS)
            if components and not any(c.get("name") == "VEVENT" for c in components):
                continue  # a task list or a journal
            name = response.props.findtext("d:displayname", default="", namespaces=NS).strip()
            calendars.append(RemoteCalendar(response.href, name or response.href))
        return calendars

    async def events(self, calendar: RemoteCalendar, start: datetime, end: datetime) -> list[str]:
        """The iCalendar data of every event resource overlapping the range."""
        body = _REPORT_RANGE.format(start=_stamp(start), end=_stamp(end))
        documents = []
        for response in await self._dav("REPORT", calendar.url, body, "1"):
            data = response.props.findtext("c:calendar-data", default="", namespaces=NS)
            if data.strip():
                documents.append(data)
        return documents

"""Command line: the commands, their options, and which code each one runs."""

from __future__ import annotations

import argparse
import asyncio
import logging
import os
import shlex
import subprocess
import sys
from datetime import UTC, datetime, timedelta
from pathlib import Path

import httpx
from pydantic import ValidationError

from . import __version__, connect, diagnose, playback, schedule, service, sources, update, wizard
from . import config as config_module
from .caldav import CalDAVError
from .config import Config, ConfigError
from .events import Event
from .runner import Runner

logger = logging.getLogger("busybar_calendar")


def _stamp(path: Path) -> tuple[int, int] | None:
    try:
        stat = path.stat()
    except OSError:
        return None
    return stat.st_mtime_ns, stat.st_size


class ConfigWatch:
    """
    Puts an edited config to work in a running service, within a minute.

    An edit that does not load leaves the service on the config it has, and
    says why in the log. `[bar]` is read only at start: a change there waits
    for `busybar-calendar restart`.
    """

    def __init__(self, path: Path, runner: Runner) -> None:
        self.path = path
        self.runner = runner
        self._stamp = _stamp(path)

    async def __call__(self) -> None:
        stamp = _stamp(self.path)
        if stamp == self._stamp:
            return
        self._stamp = stamp
        running = self.runner.config
        try:
            config = config_module.load(self.path)
            items = connect.make_sources(config)
        except EXPECTED as error:
            logger.warning(
                "%s changed, but the service keeps the config it has: %s",
                self.path,
                "; ".join(describe(error)),
            )
            return
        if config.bar != running.bar:
            logger.warning("[bar] changed: `busybar-calendar restart` puts it to use")
            config = config.model_copy(update={"bar": running.bar})
        retired = self.runner.sources
        self.runner.reconfigure(config, items)
        await connect.close_all(retired)
        logger.info("%s changed: reloaded, %d calendar source(s)", self.path, len(items))


async def run_service(config: Config, path: Path | None = None) -> int:
    """
    Keep the bar in step with the calendars until a signal, or a source that
    cannot work; with the config's `path`, follow its edits too.
    """
    items = connect.make_sources(config)
    bar = connect.make_bar(config)
    stop = connect.stop_on_signals()
    # `status` reads this line to tell which version the service runs.
    logger.info(
        "busybar-calendar %s started: %d calendar source(s), bar %s",
        __version__,
        len(items),
        config.bar.address or "via BUSY Cloud",
    )
    runner = Runner(config, bar, items)
    try:
        await runner.run(stop, ConfigWatch(path, runner) if path is not None else None)
    except sources.FatalSourceError as error:
        print(f"busybar-calendar: {error}", file=sys.stderr)
        return 1
    finally:
        await connect.close_all(runner.sources)
        await bar.aclose()
    return 0


async def cmd_run(config: Config, args: argparse.Namespace) -> int:
    return await run_service(config, args.config_path)


async def cmd_check(config: Config, args: argparse.Namespace) -> int:
    return await diagnose.check(config, as_json=args.json)


async def cmd_replay(config: Config, args: argparse.Namespace) -> int:
    return await playback.replay(config, args.day, args.seconds, args.quiet)


async def cmd_demo(config: Config, args: argparse.Namespace) -> int:
    return await playback.demo(config, args)


async def cmd_install(config: Config, args: argparse.Namespace) -> int:
    """Run the service in the background from now on: at login, restarted if it stops."""
    plan = service.install_plan(args.config_path, auto_update=args.auto_update)
    if args.dry_run:
        print(f"Would write {plan.path}:\n")
        print(plan.content.decode())
        print("Would run:")
        for command in [*plan.cleanup, *plan.commands]:
            print("  " + shlex.join(command))
        return 0
    if not args.force:
        print("Checking the setup first.\n")
        if await diagnose.check(config):
            print("Fix the problems above, or install anyway with --force.")
            return 1
        print()
    service.install(plan)
    print(f"Installed {plan.path}.")
    print("It runs at login, comes back if it stops, and reads", args.config_path.resolve())
    if args.auto_update:
        print(f"At every start and restart it first runs `{' '.join(update.upgrade_command())}`.")
    if plan.log:
        print(f"Log: {plan.log}")
    print("Remove it with: busybar-calendar uninstall")
    return 0


def cmd_restart(_args: argparse.Namespace) -> int:
    """Restart the background service, after a password or the config changed."""
    if service.restart():
        print("Restarted. `busybar-calendar status` shows how it is doing.")
        return 0
    print("Not installed: `busybar-calendar install` runs it in the background.")
    return 1


def cmd_uninstall(args: argparse.Namespace) -> int:
    plan = service.uninstall_plan()
    if args.dry_run:
        print(f"Would remove {plan.path} and run:")
        for command in [*plan.cleanup, *plan.commands]:
            print("  " + shlex.join(command))
        return 0
    if service.uninstall(plan):
        print(f"Stopped and removed {plan.path}.")
    else:
        print("Not installed.")
    return 0


async def cmd_calendars(config: Config, _args: argparse.Namespace) -> int:
    items = connect.make_sources(config)
    try:
        for item in items:
            if isinstance(item, sources.CalDAVSource):
                found = await item.calendars()
                used, unmatched = sources.select(found, item.config.include, item.config.exclude)
                print(f"{item.name} (caldav): {len(found)} calendars, {len(used)} used")
                width = max((len(calendar.id) for calendar in found), default=0)
                for calendar in found:
                    mark = "*" if calendar in used else " "
                    print(f"  {mark} {calendar.id:<{width}}  {calendar.name}")
                for pattern in unmatched:
                    print(f"  ! no calendar matches {pattern!r}")
            else:
                print(f"{item.name} (ics): one calendar, {item.config.url}")
    finally:
        await connect.close_all(items)
    print("\n* = used. Filter with include/exclude by id, name or URL; * and ? are wildcards.")
    return 0


def upcoming_notes(config: Config, event: Event) -> str:
    """What the bar does with an event, and why: its settings, your answer, its rules."""
    ref = event.calendar
    reminder, status = config.settings_for(ref.source, ref.name, ref.id, event.title)
    notes = []
    if reminder.enabled:
        notes.append(f"reminder {reminder.minutes_before}m")
    if schedule.shows_status(event, status):
        notes.append(f"status {status.show}")
    notes = notes or ["hidden"]
    if event.response != "accepted":
        notes.append(event.response)
    if patterns := config.title_patterns(event.title):
        notes.append("titles " + " ".join(map(repr, patterns)))
    return ", ".join(notes)


async def cmd_upcoming(config: Config, args: argparse.Namespace) -> int:
    now = datetime.now(UTC)
    runner = await connect.read_calendars(config, now)
    tz = connect.floating_tz(config)
    horizon = now + timedelta(hours=args.hours)
    shown = [e for e in runner.events if e.end > now and e.start < horizon]
    for event in sorted(shown, key=lambda e: e.start):
        start = event.start.astimezone(tz)
        end = event.end.astimezone(tz)
        print(
            f"{start:%a %d %b %H:%M}-{end:%H:%M}  [{event.calendar.source}/"
            f"{event.calendar.name}]  {event.title}  ({upcoming_notes(config, event)})"
        )
    screen = schedule.choose(now, runner.events, runner.settings_for)
    print(f"\nNow on the bar: {screen.kind + ': ' + screen.event.title if screen else 'nothing'}")
    return 0


def setup_logging(verbose: bool) -> None:
    logging.basicConfig(
        level=logging.DEBUG if verbose else logging.INFO,
        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
    )
    if not verbose:
        logging.getLogger("busylib").setLevel(logging.WARNING)
        logging.getLogger("httpx").setLevel(logging.WARNING)
        logging.getLogger("httpx2").setLevel(logging.WARNING)
    # Its bounds check ignores anchors, so a bottom-anchored line at y=16 -
    # busylib's own calibrated two-line layout - is reported as off-screen.
    logging.getLogger("busylib.client.display").setLevel(logging.ERROR)
    # "Device API minor version is behind Busy Lib": busylib's own nag, on every
    # bar that runs released firmware; `check` prints both versions instead.
    logging.getLogger("busylib.client.firmware").setLevel(logging.ERROR)
    # It logs every refused call; this service reports those itself, with what to do.
    logging.getLogger("busylib.client.base").setLevel(logging.CRITICAL)


FIRST_STEPS = """\
busybar-calendar shows your CalDAV and ICS calendars on a BUSY Bar: a
reminder before each event, then a red BUSY while it runs.

No config yet. To set it up:

  busybar-calendar init       a few questions: how to reach the bar, which calendar
  busybar-calendar check      proves it works, or says what to fix
  busybar-calendar install    runs it in the background from now on

busybar-calendar --help lists every command."""


def _status(args: argparse.Namespace, as_json: bool = False) -> int | None:
    """
    `status`, which needs no config for its service part, and takes a broken
    one in its stride: a running service keeps the last config that loaded,
    so it is reported beside the problems. None when there is no config yet.
    """
    try:
        path = config_module.find(args.config)
    except ConfigError:
        path = None
    if path is None or not path.is_file():
        if as_json:
            return asyncio.run(diagnose.status(None, as_json=True))
        return None
    try:
        config, problems = config_module.load(path), []
    except EXPECTED as error:
        config, problems = None, describe(error)
    return asyncio.run(diagnose.status(config, as_json, path=path, problems=problems))


def _where_you_stand(args: argparse.Namespace) -> int:
    """`busybar-calendar` alone: first steps before a config exists, the status after."""
    code = _status(args)
    if code is None:
        print(FIRST_STEPS)
        return 0
    print("\nbusybar-calendar --help lists every command.")
    return code


# The failures a user can meet and fix: reported in a line or two, never a traceback.
EXPECTED = (
    ValidationError,
    ConfigError,
    CalDAVError,
    sources.FatalSourceError,
    httpx.HTTPError,
    subprocess.CalledProcessError,
    OSError,
    ValueError,
)


def describe(error: BaseException) -> list[str]:
    """An expected failure in the user's terms: what went wrong, where."""
    if isinstance(error, ValidationError):  # the config: one line per problem
        return [
            f"{'.'.join(str(part) for part in problem['loc']) or 'config'}: "
            f"{problem['msg'].removeprefix('Value error, ')}"
            for problem in error.errors()
        ]
    if isinstance(error, httpx.RequestError):
        return [f"cannot reach {error.request.url}: {error}"]
    if isinstance(error, subprocess.CalledProcessError):  # launchctl, systemctl
        return [f"{shlex.join(error.cmd)} failed (exit {error.returncode})"]
    return [str(error)]


def _update_first() -> None:
    """`run --auto-update`, before the config is read - a newer version may be what reads
    it - and once: not again in the process an update restarts into."""
    if not os.environ.get(update.UPDATED_ENV) and update.update():
        update.restart_into_update()


def _restart_after(code: int) -> int:
    """After the config changed: a running background service reads it only when it starts."""
    if code == 0 and service.restart():
        print("Restarted the background service, so it reads the new config.")
    return code


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(prog="busybar-calendar", description=__doc__)
    parser.add_argument(
        "-c",
        "--config",
        help="TOML configuration (default: $BUSYBAR_CALENDAR_CONFIG, ./config.toml, "
        "then ~/.config/busybar-calendar/config.toml)",
    )
    parser.add_argument("-v", "--verbose", action="store_true")
    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
    # No command: where you stand, and what to do next (see _where_you_stand).
    commands = parser.add_subparsers(dest="command")
    run = commands.add_parser("run", help="keep the bar in step with the calendars")
    run.add_argument(
        "--auto-update",
        action="store_true",
        help="first update a uv tool installed from git to its latest version",
    )
    init = commands.add_parser("init", help="answer a few questions to write the config")
    init.add_argument("--force", action="store_true", help="replace an existing config")
    commands.add_parser("add", help="add another calendar to the config, a few questions")
    check = commands.add_parser("check", help="check the bar, its token and every calendar")
    check.add_argument("--json", action="store_true", help="the findings as JSON")
    status = commands.add_parser(
        "status", help="is it running, and what is on the bar now and next"
    )
    status.add_argument("--json", action="store_true", help="the same, as JSON")
    install = commands.add_parser(
        "install", help="run in the background from now on (launchd / systemd)"
    )
    install.add_argument("--dry-run", action="store_true", help="show what it would do")
    install.add_argument("--force", action="store_true", help="install even if check fails")
    install.add_argument(
        "--auto-update",
        action="store_true",
        help="update to the latest version at every start and restart (uv tool from git)",
    )
    commands.add_parser("restart", help="restart the background service, e.g. after a new password")
    uninstall = commands.add_parser("uninstall", help="stop and remove the background service")
    uninstall.add_argument("--dry-run", action="store_true", help="show what it would do")
    commands.add_parser("calendars", help="list the calendars each CalDAV source has")
    upcoming = commands.add_parser("upcoming", help="list the events the bar will show")
    upcoming.add_argument("--hours", type=int, default=24)
    demo = commands.add_parser("demo", help="draw a sample event on the bar")
    demo.add_argument("--title", default="Weekly sync with the team")
    demo.add_argument("--minutes", type=int, default=5, help="reminder: minutes to the start")
    demo.add_argument("--status", action="store_true", help="draw the in-event status instead")
    demo.add_argument("--show", help="status to draw: name, meeting, on_call, ...")
    demo.add_argument("--font", choices=["tiny", "small", "global"])
    demo.add_argument("--sound", action="store_true")
    demo.add_argument("--seconds", type=int, default=20, help="how long to leave it up")
    replay = commands.add_parser(
        "replay", help="play a day's events on the bar one after another, in short slots"
    )
    replay.add_argument("--day", default="tomorrow", help="today, tomorrow or YYYY-MM-DD")
    replay.add_argument("--seconds", type=int, default=60, help="slot per event")
    replay.add_argument("--quiet", action="store_true", help="no sounds")
    args = parser.parse_args(argv)

    setup_logging(args.verbose)

    handlers = {
        "run": cmd_run,
        "check": cmd_check,
        "install": cmd_install,
        "calendars": cmd_calendars,
        "upcoming": cmd_upcoming,
        "demo": cmd_demo,
        "replay": cmd_replay,
    }
    try:
        if args.command == "uninstall":  # needs no config: there may be none left
            return cmd_uninstall(args)
        if args.command == "restart":
            return cmd_restart(args)
        if args.command is None:
            return _where_you_stand(args)
        if args.command == "status":
            code = _status(args, args.json)
            return asyncio.run(diagnose.status(None)) if code is None else code
        if args.command == "init":  # writes the config
            path = Path(
                args.config
                or os.environ.get(config_module.CONFIG_ENV)
                or config_module.search_paths()[-1]
            )
            return _restart_after(wizard.run(path, overwrite=args.force))
        if args.command == "add":  # appends to the config
            return _restart_after(wizard.add(config_module.find(args.config)))
        if args.command == "run" and args.auto_update:
            _update_first()
        args.config_path = config_module.find(args.config)
        config = config_module.load(args.config_path)
        return asyncio.run(handlers[args.command](config, args))
    except EXPECTED as error:
        for line in describe(error):
            print(f"busybar-calendar: {line}", file=sys.stderr)
        return 1
    except KeyboardInterrupt:
        return 130