quick-cita-cr

## What it is quick-cita-cr is a personal monitoring tool for appointment openings on Costa Rica's Educación Vial portal. It signs in with your own account credentials, checks the practical-test branches you configure, keeps a local record of what it has already seen, and notifies you when new or earlier dates show up. The README states the project was validated locally against the live portal. It also notes one known limitation: during validation, Cloudflare challenges did not resolve reliably in pure headless mode, so headed mode, a virtual display, or a warmed persistent profile is recommended for unattended deployments. ## Reported capabilities The README lists these features: - Branch-by-branch appointment monitoring. - Alerts for new dates, an earlier best date, and a configurable "quick window" of days. - SQLite state so repeated runs only alert on meaningful changes. - Gmail SMTP notifications using app passwords. - A persistent Chrome profile to retain cookies and session state. - Human-like typing, clicks, delays, and scrolling. - Chrome anti-detection flags through `undetected_chromedriver`. - A `uv`-based Python project with tests, linting, and type checks. - systemd user timer templates for Linux / Oracle Cloud. The README's status section says the Cloudflare challenge resolved in headed mode, login worked with a persistent profile, the practical-test flow reached branch availability, appointment dates were extracted and compared against SQLite state, and email notification formatting worked. ## Requirements - Python 3.12 or 3.13 - `uv` - Chrome or Chrome for Testing - An Educación Vial account - A receipt number for the practical-test flow - Optionally, a Gmail app password for email notifications ## Getting started Clone the repository, run `uv sync`, then `uv run quick-cita init`. Secrets live in `~/.config/quick-cita-cr/secrets.env` (the README suggests `chmod 600`), and branches plus browser settings live in `~/.config/quick-cita-cr/config.yaml`. Diagnostics are available via `uv run quick-cita doctor`. A single visible check can be run with `uv run quick-cita check --headed`, and continuous monitoring with `uv run quick-cita watch --headed`. There is also a `demo` command that opens a visible browser, uses the persistent profile, checks the configured branches, and prints the appointment summary even when there are no new alert events. ## Configuration areas The YAML config covers three groups: - **appointment** — license class, the list of branches, `quick_window_days`, and switches for first-run, new-date, earlier-best and within-window notifications. - **schedule** — interval in minutes, jitter percent, maximum failures before pausing, and how long to pause after failures. - **browser** — headless flag, Chrome executable path, profile directory, and timeout. Notifications currently support email through Gmail SMTP (host, port, from address, recipient list). Secrets such as ID type, identification number, password, receipt number, and email credentials are read from environment variables or the secrets file. ## Chrome without sudo For machines without a system-installed Linux Chrome and without `sudo`, the README provides a sequence to download Chrome for Testing into `~/.local/share/quick-cita-cr/chrome-for-testing`, unzip it with a short Python snippet, and mark the binary and crashpad handler executable. The `executable_path` in the config then points at that extracted binary. ## Development and layout Development commands include `uv sync --all-groups`, `ruff format`, `ruff check`, `mypy` on `src/quick_cita_cr`, and `pytest`. The source tree groups browser automation (driver, Cloudflare solver, human behavior helpers), notification backends, a Typer CLI, config and secret models, the portal client, an appointment-date parser, SQLite storage, and the watcher that compares snapshots and detects events. Tests, GitHub Actions CI, systemd deployment templates, and deployment/security docs sit alongside. ## Security note The README warns against committing credentials, `.env` files, SQLite state, browser profiles, cookies, screenshots, logs, or authenticated HTML, and points to `docs/security.md`. ## License MIT.