youpdated 0.4.0__tar.gz → 0.5.0__tar.gz

{youpdated-0.4.0 → youpdated-0.5.0}/ADDING_SOURCES.md

@@ -4,7 +4,7 @@ A source is one class with two methods. This guide builds a complete, working on
 
 > Youpdated now ships a fuller `pypi` source ([youpdated/sources/pypi.py](youpdated/sources/pypi.py)).
 > The version here is kept short to teach the contract. If you build it to follow along, give it
-> another `name`: a plugin whose name is already taken by a built-in source is ignored.
+> another `name`: duplicate named plugins are ignored.
 
 - [The contract](#the-contract)
 - [Two ways to add one](#two-ways-to-add-one)
@@ -93,7 +93,7 @@ so name the offending value and say what was expected.
 
 ## Step 2: fetch updates
 
-`fetch()` gets one target and the shared `Client`. **Always use that client** never `httpx` or `requests` directly. It applies the user's proxy, rotates user agents, paces requests per host, and clears cookies.
+`fetch()` gets one target and the shared `Client`. **Always use that client** never `httpx` or `requests` directly. It applies the user's proxy, rotates user agents, paces requests per host, and keeps no cookies.
 
 ```python
 def fetch(self, target: Target, client: Client) -> Iterable[Update]:
@@ -111,7 +111,7 @@ Useful arguments:
 | --- | --- |
 | `conditional=True` | Send ETag/Last-Modified and get `None` on a 304. Use it for anything polled repeatedly. |
 | `soft_statuses=(404,)` | Return the response instead of raising, when a status is expected. itch answers 404 for a game with no devlog. |
-| `headers={...}` | Extra request headers. The user agent is added for you. |
+| `headers={...}` | Extra request headers. The user agent is added for you. These are dropped on a redirect to another host, so put a key or token here, never in the URL, which `-v`, `--test`, and errors print. |
 | `retries=0` | Skip retries when you're probing a fallback and want to fail fast. |
 
 Any other non-200 raises `FetchError`, which the runner catches and reports without killing.
@@ -124,6 +124,10 @@ from youpdated.sources.feed import parse_feed
 return parse_feed(fetched.content, source=self.name, target=target.key, tags=("release",))
 ```
 
+A body that isn't a feed, such as a web page, raises `FetchError` instead of reading as an empty feed. A fetch that returns nothing counts as a target with nothing in it, and a first fetch records that as its baseline, so raise rather than return `[]` when you can't tell what the target holds.
+
+Update fields are cleaned when an `Update` is made: control characters and lone surrogates are dropped and a non-string title becomes text, so the terminal, `--rss`, and `--json` are safe from what a site sends.
+
 ## The complete source
 
 ```python
@@ -137,7 +141,7 @@ from typing import Any, ClassVar, Iterable
 from youpdated.http import Client
 from youpdated.models import Target, Update
 from youpdated.registry import register
-from youpdated.sources.base import ConfigEntryError, entry_fields, require
+from youpdated.sources.base import ConfigEntryError, entry_fields, parse_iso, require
 
 MAX_VERSIONS = 10
 
@@ -171,7 +175,7 @@ class PyPISource:
         for version, files in (doc.get("releases") or {}).items():
             if not files or all(f.get("yanked") for f in files):
                 continue
-            dated.append((version, _parse_iso(files[0].get("upload_time_iso_8601"))))
+            dated.append((version, parse_iso(files[0].get("upload_time_iso_8601"))))
         dated.sort(
             key=lambda pair: pair[1] or datetime.min.replace(tzinfo=timezone.utc), reverse=True
         )
@@ -190,18 +194,10 @@ class PyPISource:
             )
             for version, published in dated[:MAX_VERSIONS]
         ]
-
-
-def _parse_iso(value: str | None) -> datetime | None:
-    if not value:
-        return None
-    try:
-        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
-    except ValueError:
-        return None
-    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
 ```
 
+`parse_iso()` reads an API's ISO 8601 timestamp, taking one with no zone as UTC, and returns `None` for anything it can't read.
+
 ## Notes
 
 ### The uid is the deduplication system
@@ -240,6 +236,25 @@ release and another ignore only the candidates.
 You do not need to handle `ignore` yourself. It is lifted off the config entry
 before `targets()` ever sees it, and applied to whatever you return.
 
+### Set `version` on anything versioned
+
+`version`: a user's `versions:` rules (only major bumps, only versions above
+`3.13`) compare it, so set it on every item that is a version, even when the
+title repeats it. Pass it as upstream writes it (`v3.15.0rc1`, `1.25.0_2`);
+only its numbers are compared. Leave it `None` on items that aren't versions,
+such as posts and commits, which the rules never filter. Like `ignore`,
+`versions` is lifted off the config entry before `targets()` sees it.
+Tag prereleases `prerelease`: `bump` counts only the first one toward a
+version, and an untagged version counts as a final release.
+
+### Listing the latest release
+
+If your source lists only the newest few items, a busy upstream can push a
+release off the list before it's seen. When the latest release is in the
+document you already fetch, list it always. When it takes a request of its
+own, ask only if `target.track_latest` is set, and add it only if it isn't
+listed already, under the uid it would have there.
+
 ### Filling in a label during fetch
 
 Sometimes the friendly name is only available from the response. Assign it to `target.label`; the renderers pick it up:
@@ -251,7 +266,7 @@ if not target.label:
 
 ### Caching a resolved value
 
-`client.state` is a small key-value store for things that are expensive to resolve and never change: the Steam source caches appid→name there, so it looks it up once ever:
+`client.state` is a small key-value store for things that are expensive to resolve and never change: the Steam source caches appid to name there, so it looks it up once:
 
 ```python
 cached = client.state.cache_get("my_namespace", key) if client.state else None
@@ -269,6 +284,12 @@ If the key is the target's `key`, list the namespace on the source so `youpdated
 caches: ClassVar[tuple[str, ...]] = ("my_namespace",)
 ```
 
+A namespace shared by every target, like YouTube's list of Invidious instances, goes in `shared_caches` instead; `--wipe` on any of the source's targets clears it whole:
+
+```python
+shared_caches: ClassVar[tuple[str, ...]] = ("my_shared_namespace",)
+```
+
 ### Recognizing your entries
 
 `youpdated add <value>` works without a source when only one source claims the value. To use, add an optional `claim()` returning the config entry for a value that can only be yours, or `None`. `accepted()` returns the entry if your `targets()` reads it, and `url_parts()` splits a URL:
@@ -286,6 +307,12 @@ def claim(self, value: str) -> str | None:
 
 Claim only what is distinguishable and unique: a host you own, or a shape no other source uses. A bare name like `httpx` could be several sources' entry, and two sources claiming a value stops both from getting it. Like `targets()`, `claim()` must not touch the network.
 
+A source that can read anything of a shape, like `webpage` reading any URL, sets `fallback`. Its claim counts only when no other source claims the value. It never claims a GitHub or itch.io URL away from the source made for it:
+
+```python
+fallback: ClassVar[bool] = True
+```
+
 ### Thread
 
 Targets are fetched concurrently. Keep everything in local variables or on the `Target`; don't mutate shared state on the source instance.
@@ -377,6 +404,7 @@ Users then configure it like any built-in source. A plugin that fails to import
 - [ ] Returns `[]` rather than inventing an update
 - [ ] `published` is timezone-aware UTC (or `None`)
 - [ ] `tags` describe the update type, so `ignore:` rules can match them
+- [ ] `version` is set on items that are versions, so `versions:` rules can compare them
 - [ ] Tests cover parsing, both config shapes, and uid stability
 - [ ] Optional: `claim()` for values only this source can mean, `caches` for namespaces keyed by target
-- [ ] Registered — `@register` plus an import, or an entry point
+- [ ] Registered: `@register` plus an import, or an entry point

{youpdated-0.4.0 → youpdated-0.5.0}/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.5.0] — 2026-11-06
+
+### Added
+
+- **`youpdated import`** (#37). Adds everything in a `package.json`, `requirements.txt`, or `Brewfile`, with `youpdated add`, `--test` shows the change without writing it. `package.json` dependencies of every kind go under `npm`, requirements go under `pypi` with `-r` includes followed, and `brew`/`cask` lines go under `homebrew`. A dependency from a path, URL, git repo, editable install, third-party tap, and Brewfile lines like `mas` are skipped with reasons shown. Files are recognized by name, or read as named with `--format`. Requirements from another index (`--index-url`, `--no-index`) are skipped, as PyPI's package of that name may be a different one, and `--extra-index-url` is shown as a warning. Credentials in a dependency's URL are never printed.
+- **Version filters** (#37). A `versions:` rule reports only some of a target's versions. `bump: major` reports a version only when its first number is higher than every release before it: 4.0.0, but not 4.0.1 or a 3.9.x backport. `minor` and `patch` do the same for the second and third numbers, and `min: "3.13"` drops versions below 3.13. Rules can be set for every source, for one, or on one entry, like `ignore:`, and an entry's rules override the others one rule at a time; `bump: any` turns a bump back off. Only the first prerelease toward a bump is reported, then the final, so a run of nightlies or canaries counts once. Versions are compared by their numbers, so any dotted or underscored scheme works (`v3.15.0rc1`, `131.0.6778.69`, `curl-8_11_1`, `REL_17_2`), and updates without a version, like commits, aren't filtered. A version left out still counts as seen, so loosening a rule doesn't report the past. A target with `bump` keeps its highest versions in its history, so a source listing only the current version (`homebrew`) has something to compare against; `rm --wipe` and `expiry:` clear. The summary says how many versions were left out, and `--json` counts them as `filtered`. A `versions:` key no source is listed under is warned about, like an `ignore:` one.
+- **`youpdated edit`** (#59). Opens the config in an editor, then saves it once the editor closes. An editor that opens a window and returns at once, like the device defaults or `code`, is waited on: save there, then press Enter. `editor:` in the config picks one over `$VISUAL` and `$EDITOR`: a command, a program's path, or (on macOS) an app's name. Smart quotes around a value, an unquoted value starting with `@`, and no-break or invisible spaces are fixed on save, and listed. An encrypted config is decrypted to a copy only you can read, under `/dev/shm` where available, and written back encrypted with the same passphrase. A config that sets `privacy.proxy` and encrypts asks before writing the copy. The edit is checked before saving. Nothing is saved when the editor exits with an error.
+- **`track_latest:`** (#37). With `track_latest: true`, `git` and `steam` entries also ask for the latest release, in case busier items pushed it off the list: where GitHub's `/releases/latest` points (the API's latest release with a token), GitLab's latest permalink, Forgejo's latest release, and the newest Steam post the developer marked as an update. It's added only when not already listed. Off by default, as it's one request more per entry.
+- **`webpage` source** (#56). Watches the version a page shows, for apps with no feed, registry, or forge: `youpdated add https://www.videolan.org/vlc/`. The version is read from the page's structured data (`softwareVersion`), then download links with a version in the file name, then text naming the latest version, then text labeling one. The first that has a version decides and must name only one, and any other naming a different one fails the check. Where the version was found is remembered, and a later check finding it elsewhere fails. `regex:` names the version location, matched against the page's HTML. A page with no version that links a feed says that in its error, and an address that is a feed points to `feed`. Prereleases (`2.5.0-beta.1`) are tagged `prerelease`; `rm --wipe` forgets where the version was found.
+- **Sorting and priority in the desktop example app** (#12). Right-click an update to mark its target high, normal, or low priority; high ones are tagged and low ones dimmed. The list sorts by priority, newest, source, or name. High targets get their own notification as soon as they update, and low ones never notify. `--digest 18:00` holds the rest for one notification a day, and `--bundle-high` holds high priority too. Settings live in the example only, beside the history as `state.desk.json` and encrypted when the history is; the youpdated config is unchanged. (example app available from the GitHub)
+- **Youpdated for Mac (beta)** (#37). A menu bar app for macOS 15+ on Apple silicon, with its own copy of the engine (no Python needed). It shares a config and history with the CLI. See [docs/macos-app.md](docs/macos-app.md).
+- **`youpdated api`** (#37). The JSON interface for desktop apps. `youpdated api serve` reads requests on stdin and answers on stdout; any other op runs once and prints a reply, for scripts: `youpdated api status --json`. Messages, a JSON Schema, and an example of every exchange are in `apps/contract/v1`. An encrypted setup is unlocked once over the pipe, and derived keys are kept in memory, so later requests don't each pay for scrypt.
+- **Priorities and the digest in `notify:`** (#37). Each target is `high`, `normal`, or `low` priority, set in the desktop app. A webhook or command gets updates at its `priority:` and above, `normal` if not configured, and `digest: false` sends them as found while the app holds a digest. `command:` also takes a mapping, with the command under `run:`. The CLI applies `priority:` and ignores `digest:`.
+
+### Changed
+
+- **`youpdated add` with a URL no source recognizes adds it under `webpage`**, instead of asking for a source. A URL another source claims (a GitHub repo, an itch.io game, a feed) still goes to that source; plugins can claim the same way with `fallback = True`.
+- **`youpdated add` lists entries already watched on one line per source** (`Already watching express, react under npm`), instead of one line each.
+- **`youpdated uninstall` also removes the package.** Once the files are gone it runs the uninstaller used for the copy: `pipx uninstall` for pipx, `uv tool uninstall` for uv tools, `uv pip uninstall` for a uv-made environment, and `python -m pip uninstall` with the interpreter it runs on otherwise. The package is listed in `--test` and confirmation prompt. If the uninstaller fails, or exits but leaves the package, the command to run yourself is printed and exits 1. On Windows, which won't delete the running `youpdated.exe`, the uninstaller runs in the background once the command exits. `--keep-package` deletes files only. `--keep-config` now removes the package too; add `--keep-package` to only wipe history. A copy run from a checkout (`python -m youpdated`, `PYTHONPATH`) is not a package, and nothing other than files are removed.
+- **One run at a time per history file.** A run holds a lock (`state.sqlite3.lock`, beside the database) and another waits up to a minute, then exits 1 saying the file is in use. An encrypted history is read whole and written back whole, so a `youpdated rm --wipe` during a scheduled check was undone, two overlapping checks could lose seen marks, and a file could be left undecryptable. `encrypt` and `decrypt` take the lock too. `uninstall` removes the lock file as well.
+- **`--since` leaves what it hides unrecorded.** A new item older than the window was recorded as seen, so only `--all` could ever show it. It is now reported by the next check without `--since`.
+- **`check --test` shows the config's problems** in the `problems` panel and exits 2 for them with `--fail-on-error`, and `--test --json` prints a report. It used to exit 0 and print nothing about them. A source that stops early for want of an answer is not counted as a problem.
+- **`git` refuses `owner/repo/extra`** for GitHub and Forgejo instead of reading it as `owner/repo`: `add hashicorp/tap/terraform` landed under `git` as `hashicorp/tap`, and `rm python/cpython/typo` removed `python/cpython`. A pasted address (`https://github.com/o/r/releases/tag/v1`, `codeberg.org/o/r/releases`) is still trimmed to the repo.
+- **A webhook is only sent again when it can't have arrived**: after a failed connection, `429`, `503`. Timeout or `500`, `502`, `504` could come after delivery, and aren't retried.
+- **Notify commands no longer inherit** `YOUPDATED_PASSPHRASE`, `GITHUB_TOKEN`, `GITLAB_TOKEN`, `YOUTUBE_API_KEY`.
+- **A warning for an `ignore:` key with no coverage**, such as `ignore: {github: …}` left behind after moving entries to `git:`. It shows after the report, and in a new `warnings` list in `--json`.
+- **`expiry:` and `--since` max out at 100y.** `never` still works.
+- **The release workflow's publish job now pins actions to exact commits**, since it holds `id-token: write` and a tag can be moved.
+- **The desktop example shows one card per target.** Several updates from the same target share its card, newest first, one line each up to three and then a count; each line opens its own link.
+- **`rm --wipe` also forgets what the desktop app stores about a target**: inbox items, priority, newest item, and icon.
+
+### Fixed
+
+- **More prereleases are recognized without a GitHub token.** The anonymous atom feeds have no prerelease flag, so the tag name is read, and now catches `-next.2` (Angular), milestones `-M2` and `.CR1` (Spring, Quarkus), `beta4` right after the version (Nextcloud), `-ea.3` (Traefik), `llvmorg-24-init`, mesa's `-branchpoint` tags, Swift's dated snapshots, and an rc with build metadata (`-rc.0+dedupelabels`). A tag without a number, like neovim's `nightly`, keeps it as its version, so it is a prerelease as the API path flags it, and a commit hash ending in `7b0` is no longer one. Checked against GitHub's own flags on 11,259 releases of 87 projects: missed prereleases went from 441 to 288, none of which have anything in the tag to go by.
+- **npm and pypi could miss a release behind prereleases.** A check read the 10 newest versions, so a package publishing canaries or nightlies faster than it was checked could push a release out before it was seen: in three years of `next`'s history, weekly checks would never have seen 42 of its final releases, or 7 of `react`'s. The 10 newest final releases and the `latest` version are now listed too, from the same request.
+- **Security: the YouTube Data API key could be printed.** It was part of the request URL, which errors, `--json`, `-v`, and `--test` show. It is now sent in the `X-Goog-Api-Key` header, which is dropped on a redirect to another host.
+- **Security: escape codes in a title, body, or link reached the terminal.** A feed could clear the screen or plant links with ``. Control characters and lone surrogates are now removed from everything a site sends, which also keeps `--rss` valid XML when a title holds one, and stops a lone surrogate from crashing `--rss` and `--json`.
+- **Security: the desktop example could run code from a title on Windows.** PowerShell ends a quoted string at curly quotes too. The text now reaches PowerShell through the environment.
+- **Updates could be lost when the report failed.** Items were recorded as seen before the report, `--rss`, and pruning ran, so a failure in any of them, such as a label with `[/…]` in the problems panel, a numeric Invidious title, or an unwritable `--rss` path, used them up unseen. The report and feed are now first. An unwritable `--rss` path is an error.
+- **An invalid entry no longer drops later entries of its source.** It is reported alone.
+- **A web page at a feed's address was an empty feed**, with no error, and on a first fetch its empty baseline reported the whole feed as new once the feed returned. It is now an error, for feeds and sources that reads one.
+- **Brave recorded an empty baseline when the GitHub API was rate-limited**, since the atom feed's 10 newest releases are nearly all nightlies, and then reported old stable releases as new. The target now fails until either path has a release for its channel, and the stable channel falls back to the release GitHub marks as latest.
+- **YouTube's fallbacks**: a malformed Invidious reply (`{"videos": [null]}`, an out-of-range date) skipped the other instances and the Data API; it now moves on. Invidious addresses from the public list are used only if they are HTTPS on a public hostname; a test had fetched `http://127.0.0.1:9`. The list is refreshed on use (once a day) instead of never; each fetch tries a random four kept instances, not just the first four, and `rm --wipe` clears.
+- **Cookies could pass between requests** run at the same time, and to the next hop of a redirect. Now none are kept.
+- **A webhook redirected with `301`, `302`, `303`.** It was resent as a request without a body, and counted as delivered. It is now a failure; `307` and `308` are still followed.
+- **A repo listed under both `github:` and `git:` with different ignore rules** was fetched fully on every run.
+- **`youpdated encrypt` on a symlinked config** replaced the link and left the plaintext at its target. It now writes through the link, same as `add`/`rm`. A write also doesn't leave a fixed-name `.tmp`, which could make the result readable by others.
+- **A GitLab group with a dot in its name** (`my.group/sub/project` with `host: gitlab.com`) was read as a hostname.
+- **A plugin whose constructor raises** crashed every command, and kept later plugins from loading. It is now skipped.
+- **Cleaner errors instead of tracebacks** for a config that isn't UTF-8, a `--state` file that isn't a database, and the desktop example given a `-c` config that doesn't exist.
+- **`uninstall` exited 0 when it left files in place.** It now exits 1.
+- **An ntfy webhook lost its query**, so `?auth=` didn't work; `headers:` was the only way.
+- **`split_command` accepted** a YAML boolean (`yes`, `off`) or an empty string in a list command.
+- **Timestamps with a fraction and a zone offset**, such as `.123+05:30`, lost the offset in the `browser` source. One parser now serves every source.
+- **Trackpad scrolling in the desktop example on macOS.** Tk 9 sends trackpads as `<TouchpadScroll>`, which the window ignored, and reports a mouse wheel notch as 120 rather than 1, which scrolled 720 pixels a notch. Tk 8.6 behaves as before.
+- **Link highlighting** has been fixed to correctly bold links without extra coloration or breakage at spaces in links.
+- **Terminal resizing** no longer adds extra lines or breaks output formatting in cli.
+
 ## [0.4.0] — 2026-10-24
 
 ### Added
@@ -35,7 +95,7 @@ All notable changes to this project are documented here. The format follows [Kee
 ### Fixed
 
 - **itch builds no longer re-report on unchanged pages.** itch.io shuffles HTML attribute order, and the upload list was only read in one order, so some fetches saw no files and fingerprinted a "new build". Successive runs each reported a different handful of games until every variant had been seen. Upload and timestamp parsing no longer depend on attribute order.
-- **YouTube Shorts no longer re-report when the feed falls back.** The official feed links Shorts as `/shorts/<id>`, which was not recognised, so Shorts were recorded as `yt:video:yt:video:<id>` there and `yt:video:<id>` through Invidious or Data API. Each switch reported Shorts again. Existing history is migrated on first open, so nothing already seen comes back.
+- **YouTube Shorts no longer re-report when the feed falls back.** The official feed links Shorts as `/shorts/<id>`, which was not recognized, so Shorts were recorded as `yt:video:yt:video:<id>` there and `yt:video:<id>` through Invidious or Data API. Each switch reported Shorts again. Existing history is migrated on first open, so nothing already seen comes back.
 - **`--no-save` really leaves the state alone.** It still stored each feed's ETag/Last-Modified, so the next real run was answered 304 and silently skipped whatever the preview had shown. (Whoops)
 - **A target that fails partway no longer hides its new items.** If one of a target's fetches failed (e.g. GitHub `watch: [releases, commits]` with commits down), the others' validators were still stored while their items were discarded, so the next run got a 304 and never reported them. Validators are now stored only alongside the items they cover.
 - **Feeds listed oldest-first report new entries.** Entries were cut to the limit in document order before sorting, so on an oldest-first feed longer than the limit the newest posts never made it in. Affects `feed`, Steam, itch devlogs, and GitHub atom feeds.
@@ -93,7 +153,7 @@ All notable changes to this project are documented here. The format follows [Kee
 
   A run now reuses each document across the targets that share it (`Client.run_scope()`), so the document is fetched once and every target sees it. The same config went from 8 requests reporting 2 of 8 targets, to 2 requests reporting 8 of 8. (And 147 ms to 43 ms of wall time) Outside a run the client is unchanged: one GET per call, and a 304 still means "nothing new".
 
-- **The YouTube official-feed path never set the channel label.** `_label_and_parse` did not do the labelling it was supposed to, so a channel that answered on the primary path was reported by its raw `@handle` while the Invidious and Data API fallbacks named it properly. The label now comes from the feed on all three paths.
+- **The YouTube official-feed path never set the channel label.** `_label_and_parse` did not do the labeling it was supposed to, so a channel that answered on the primary path was reported by its raw `@handle` while the Invidious and Data API fallbacks named it properly. The label now comes from the feed on all three paths.
 
 - **`feed` sources parsed every feed twice** A `feed:` entry given as a bare URL had no label, so `FeedSource.fetch` parsed the document once to read the feed's own `<title>` and then handed the same bytes to `parse_feed`, which parsed them again. Feed parsing is the most expensive part of a run, so this ~doubled the CPU cost of every bare-URL feed. One parse now feeds both the label and the entries.
 
@@ -167,6 +227,7 @@ First release.
 - Firefox publishes current versions, so it reports one item per channel.
 - Edge exposes release notes only for the stable and beta channels. (But like, it's Edge, why do you want to know when it updates?)
 
+[0.5.0]: https://github.com/Void1-1/youpdated/releases/tag/v0.5.0
 [0.4.0]: https://github.com/Void1-1/youpdated/releases/tag/v0.4.0
 [0.3.1]: https://github.com/Void1-1/youpdated/releases/tag/v0.3.1
 [0.3.0]: https://github.com/Void1-1/youpdated/releases/tag/v0.3.0

{youpdated-0.4.0 → youpdated-0.5.0}/CONTRIBUTING.md

@@ -72,7 +72,7 @@ TLDR: implement `targets()` and `fetch()` from the protocol in [youpdated/source
 
 ## Building a release
 
-Publishing is done by [.github/workflows/release.yml](.github/workflows/release.yml) when a GitHub Release is published. It runs the full test matrix, builds, checks the tag matches the version in `pyproject.toml`, installs the built wheel to make sure it runs, and uploads to PyPI through trusted publishing. No PyPI token is stored.
+Publishing is done by [.github/workflows/release.yml](.github/workflows/release.yml) when a GitHub Release tagged `v*` is published. It runs the full test matrix, builds, checks the tag matches the version in `pyproject.toml`, installs the built wheel to make sure it runs, and uploads to PyPI through trusted publishing. No PyPI token is stored.
 
 1. Bump `version` in `pyproject.toml` and add the matching `CHANGELOG.md` entry in the same commit.
    **A version is permanent:** PyPI refuses to replace an existing version even after a delete.

{youpdated-0.4.0 → youpdated-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: youpdated
-Version: 0.4.0
+Version: 0.5.0
 Summary: Simple update tracker for games, apps, and packages
 Author-email: Void1-1 <161782542+Void1-1@users.noreply.github.com>
 License-Expression: MIT
@@ -39,18 +39,36 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: respx>=0.21; extra == "dev"
 Requires-Dist: cryptography>=42.0; extra == "dev"
+Requires-Dist: jsonschema>=4.18; extra == "dev"
 Provides-Extra: publish
 Requires-Dist: build>=1.2; extra == "publish"
 Requires-Dist: twine>=5.0; extra == "publish"
 Dynamic: license-file
 
-# Youpdated
-
-[![tests](https://github.com/Void1-1/youpdated/actions/workflows/tests.yml/badge.svg)](https://github.com/Void1-1/youpdated/actions/workflows/tests.yml)
-
-Youpdated keeps track of the games, apps, and packages you follow, and tells you what changed since you last checked in.
-
-It is built to be **privacy-preserving, anonymous, and customizable**: no accounts, no API keys required, nothing stored anywhere non-local.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Void1-1/youpdated/main/.github/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/Void1-1/youpdated/main/.github/assets/logo-light.png" alt="Youpdated" width="340">
+  </picture>
+</p>
+
+<p align="center">
+  Youpdated keeps track of the games, apps, and packages you follow, and lets you know about updates or changes.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/youpdated/"><img src="https://img.shields.io/pypi/v/youpdated?color=006C7D&label=PyPI" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/youpdated/"><img src="https://img.shields.io/pypi/pyversions/youpdated?color=006C7D&label=Python" alt="Supported Python versions"></a>
+  <a href="https://github.com/Void1-1/youpdated/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/Void1-1/youpdated/tests.yml?branch=main&label=Tests" alt="Test status"></a>
+  <a href="https://github.com/Void1-1/youpdated/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Void1-1/youpdated?color=006C7D&label=License" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#get-started">Get started</a> ·
+  <a href="#sources">Sources</a> ·
+  <a href="https://github.com/Void1-1/youpdated/blob/main/docs/macos-app.md">Youpdated MacOS App (beta)</a> ·
+  <a href="#learn-more">Docs</a>
+</p>
 
 ```text
 ╭─ steam ──────────────────────────────────────────────────────────╮
@@ -78,9 +96,12 @@ It is built to be **privacy-preserving, anonymous, and customizable**: no accoun
 | `youtube` | New videos on a channel or playlist |
 | `browser` | New Chrome, Brave, Firefox, and Edge releases |
 | `feed` | Anything else with an RSS or Atom feed |
+| `webpage` | The version a download page shows, for anything with no feed |
 
 ## Get started
 
+On a Mac and want an app version? [Youpdated for Mac](https://github.com/Void1-1/youpdated/blob/main/docs/macos-app.md) is in beta.
+
 ### 1. Install
 
 Works on macOS, Linux, and Windows. Needs **Python 3.11 or newer** (`python3 --version` to check). Then:
@@ -116,11 +137,13 @@ youpdated add npm react
 youpdated add youtube @NASA
 ```
 
-A link or handle that can only work with one source doesn't need to be named: `youpdated add https://github.com/neovim/neovim`.
+A link or handle that can only work with one source doesn't need to be named: `youpdated add https://github.com/neovim/neovim`. Any other web address goes under `webpage`.
+
+To watch all dependencies of a project, import its `package.json`, `requirements.txt`, or `Brewfile`: `youpdated import package.json`.
 
 The starter config comes with examples; `youpdated rm` to remove any you don't want.
 
-Or open the file and list them under each source yourself:
+Or run `youpdated edit` to open the file and list them under each source yourself:
 
 ```yaml
 sources:
@@ -155,6 +178,7 @@ youpdated check
 | A YouTube playlist | `playlist: PLxxxx` | The `list=` part of the playlist URL. A full playlist URL also works. |
 | A browser | `chrome`, `brave`, `firefox`, `edge` | Just the name. |
 | Anything else | `https://example.com/feed.xml` | Any RSS or Atom feed URL. Many sites publish one at `/feed.xml`, `/releases.atom`, or `/blog/rss`. |
+| Anything without a feed | `https://www.videolan.org/vlc/` | The download page's URL. The version is read off the page. See [Web pages](docs/configuration.md#web-pages). |
 
 ## Basic commands
 
@@ -166,7 +190,9 @@ youpdated check -s steam     # only one source
 youpdated check --test -v    # check your config without fetching anything
 youpdated add npm react      # start watching something
 youpdated remove npm react   # stop watching it
-youpdated uninstall          # remove Youpdated files
+youpdated import Brewfile    # watch everything a package.json, requirements.txt, or Brewfile lists
+youpdated edit               # open the config in your default editor
+youpdated uninstall          # remove Youpdated and its files
 ```
 
 ## Privacy
@@ -177,6 +203,7 @@ youpdated uninstall          # remove Youpdated files
 
 ## Learn more
 
+- [Youpdated for Mac](https://github.com/Void1-1/youpdated/blob/main/docs/macos-app.md): the menu bar app, in beta
 - [Configuration](https://github.com/Void1-1/youpdated/blob/main/docs/configuration.md): all options, ignoring update types, and how long history is kept
 - [Usage](https://github.com/Void1-1/youpdated/blob/main/docs/usage.md): all commands, JSON and RSS output, and running on a schedule
 - [Notifications](https://github.com/Void1-1/youpdated/blob/main/docs/notifications.md): get updates on your phone, Discord, Slack, or to a script

{youpdated-0.4.0 → youpdated-0.5.0}/README.md

@@ -1,10 +1,27 @@
-# Youpdated
-
-[![tests](https://github.com/Void1-1/youpdated/actions/workflows/tests.yml/badge.svg)](https://github.com/Void1-1/youpdated/actions/workflows/tests.yml)
-
-Youpdated keeps track of the games, apps, and packages you follow, and tells you what changed since you last checked in.
-
-It is built to be **privacy-preserving, anonymous, and customizable**: no accounts, no API keys required, nothing stored anywhere non-local.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Void1-1/youpdated/main/.github/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/Void1-1/youpdated/main/.github/assets/logo-light.png" alt="Youpdated" width="340">
+  </picture>
+</p>
+
+<p align="center">
+  Youpdated keeps track of the games, apps, and packages you follow, and lets you know about updates or changes.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/youpdated/"><img src="https://img.shields.io/pypi/v/youpdated?color=006C7D&label=PyPI" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/youpdated/"><img src="https://img.shields.io/pypi/pyversions/youpdated?color=006C7D&label=Python" alt="Supported Python versions"></a>
+  <a href="https://github.com/Void1-1/youpdated/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/Void1-1/youpdated/tests.yml?branch=main&label=Tests" alt="Test status"></a>
+  <a href="https://github.com/Void1-1/youpdated/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Void1-1/youpdated?color=006C7D&label=License" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#get-started">Get started</a> ·
+  <a href="#sources">Sources</a> ·
+  <a href="https://github.com/Void1-1/youpdated/blob/main/docs/macos-app.md">Youpdated MacOS App (beta)</a> ·
+  <a href="#learn-more">Docs</a>
+</p>
 
 ```text
 ╭─ steam ──────────────────────────────────────────────────────────╮
@@ -32,9 +49,12 @@ It is built to be **privacy-preserving, anonymous, and customizable**: no accoun
 | `youtube` | New videos on a channel or playlist |
 | `browser` | New Chrome, Brave, Firefox, and Edge releases |
 | `feed` | Anything else with an RSS or Atom feed |
+| `webpage` | The version a download page shows, for anything with no feed |
 
 ## Get started
 
+On a Mac and want an app version? [Youpdated for Mac](https://github.com/Void1-1/youpdated/blob/main/docs/macos-app.md) is in beta.
+
 ### 1. Install
 
 Works on macOS, Linux, and Windows. Needs **Python 3.11 or newer** (`python3 --version` to check). Then:
@@ -70,11 +90,13 @@ youpdated add npm react
 youpdated add youtube @NASA
 ```
 
-A link or handle that can only work with one source doesn't need to be named: `youpdated add https://github.com/neovim/neovim`.
+A link or handle that can only work with one source doesn't need to be named: `youpdated add https://github.com/neovim/neovim`. Any other web address goes under `webpage`.
+
+To watch all dependencies of a project, import its `package.json`, `requirements.txt`, or `Brewfile`: `youpdated import package.json`.
 
 The starter config comes with examples; `youpdated rm` to remove any you don't want.
 
-Or open the file and list them under each source yourself:
+Or run `youpdated edit` to open the file and list them under each source yourself:
 
 ```yaml
 sources:
@@ -109,6 +131,7 @@ youpdated check
 | A YouTube playlist | `playlist: PLxxxx` | The `list=` part of the playlist URL. A full playlist URL also works. |
 | A browser | `chrome`, `brave`, `firefox`, `edge` | Just the name. |
 | Anything else | `https://example.com/feed.xml` | Any RSS or Atom feed URL. Many sites publish one at `/feed.xml`, `/releases.atom`, or `/blog/rss`. |
+| Anything without a feed | `https://www.videolan.org/vlc/` | The download page's URL. The version is read off the page. See [Web pages](docs/configuration.md#web-pages). |
 
 ## Basic commands
 
@@ -120,7 +143,9 @@ youpdated check -s steam     # only one source
 youpdated check --test -v    # check your config without fetching anything
 youpdated add npm react      # start watching something
 youpdated remove npm react   # stop watching it
-youpdated uninstall          # remove Youpdated files
+youpdated import Brewfile    # watch everything a package.json, requirements.txt, or Brewfile lists
+youpdated edit               # open the config in your default editor
+youpdated uninstall          # remove Youpdated and its files
 ```
 
 ## Privacy
@@ -131,6 +156,7 @@ youpdated uninstall          # remove Youpdated files
 
 ## Learn more
 
+- [Youpdated for Mac](https://github.com/Void1-1/youpdated/blob/main/docs/macos-app.md): the menu bar app, in beta
 - [Configuration](https://github.com/Void1-1/youpdated/blob/main/docs/configuration.md): all options, ignoring update types, and how long history is kept
 - [Usage](https://github.com/Void1-1/youpdated/blob/main/docs/usage.md): all commands, JSON and RSS output, and running on a schedule
 - [Notifications](https://github.com/Void1-1/youpdated/blob/main/docs/notifications.md): get updates on your phone, Discord, Slack, or to a script

{youpdated-0.4.0 → youpdated-0.5.0}/SECURITY.md

@@ -32,8 +32,9 @@ Youpdated is a local CLI that reads public endpoints. The interesting attack sur
   sent to any host other than the one they belong to, including by following a redirect. The same
   goes for headers set on a webhook. Webhook URLs carry their secret in the path and must never be
   logged or shown beyond their host.
-- **`youpdated uninstall`.** It deletes files. Any way to make it remove something outside its own
-  config and data directories is in scope.
+- **`youpdated uninstall`.** It deletes files and uninstalls the package. Any way to make it remove
+  something outside its own config and data directories, or uninstall anything but the running copy of
+  Youpdated, is in scope.
 - **Encryption at rest.** When the config or history is encrypted, the passphrase and the decrypted
   contents must exist only in memory. Anything that writes plaintext to disk, logs the passphrase,
   accepts a file whose authentication tag does not verify, lets the KDF parameters be weakened, or

{youpdated-0.4.0 → youpdated-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "youpdated"
-version = "0.4.0"
+version = "0.5.0"
 description = "Simple update tracker for games, apps, and packages"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -56,7 +56,7 @@ dependencies = [
 
 [project.optional-dependencies]
 encryption = ["cryptography>=42.0"]
-dev = ["pytest>=8.0", "respx>=0.21", "cryptography>=42.0"]
+dev = ["pytest>=8.0", "respx>=0.21", "cryptography>=42.0", "jsonschema>=4.18"]
 publish = ["build>=1.2", "twine>=5.0"]
 
 [project.urls]

{youpdated-0.4.0 → youpdated-0.5.0}/youpdated/__init__.py

@@ -1,3 +1,3 @@
 """Youpdated, a simple update tracker."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"