Library Watchlist Monitor

Closed whitelist monitor for library/tool versions.

What this does

This monitor checks only the packages listed in library-watch/watchlist.yml. It does not discover related packages, install updates, modify dependencies, open PRs, or create commits.

Run it from the repository root:

python3 library-watch/scripts/check_versions.py

Self-check:

python3 library-watch/scripts/check_versions.py --self-test

Config lives in library-watch/watchlist.yml. It is JSON-compatible YAML so the script stays stdlib-only.

Supported source_type values:

• github_release with source like owner/repo
• npm with source like package-name
• NEEDS_SOURCE to skip remote lookup until an exact source is configured

Reports are written to library-watch/runs/YYYY-MM-DD-HHMM.md. Structured output is written to library-watch/runs/YYYY-MM-DD-HHMM.json. State is written to library-watch/state.json. HTTP cache is written to library-watch/.cache/. These generated files are ignored by git.

No installs, updates, dependency edits, PRs, or commits are performed.

LLM-assisted runs

The intended workflow is to let an LLM execute the monitor, read the generated JSON report, append analysis to the generated Markdown report, and post a short summary. It can run on demand or on a schedule.

Use:

• Working directory: the repository root
• Command: python3 library-watch/scripts/check_versions.py
• Schedule: optional, for example every 2 days
• Notification: post the generated Markdown and JSON report paths after each run

The script collects facts. The LLM adds judgment. Without the LLM analysis, this is only a version check.

After each LLM-assisted run, append a ## Analisis LLM section to the generated Markdown report based only on the generated JSON report:

• Overall run summary: what changed, what did not, and whether action is needed.
• Package-level impact: local version, latest version, update availability, remote change, status, errors, source/release links, and update command.
• Changelog impact: summarize changelog from the JSON report when present.
• Missing impact: write No changelog impact found when changelog impact is absent; do not infer from unrelated sources.
• Recommendation: no action, review changelog, update manually, or blocked by error, with the reason.
• Precautions: only package-specific precautions supported by the JSON report.

The JSON report should remain the source of truth. The Markdown report is for humans, so the LLM analysis belongs there.

Automation prompt template:

From the repository root, run:

python3 library-watch/scripts/check_versions.py

Use the generated JSON report printed by the script as the only source of truth.
Open the generated Markdown report printed by the script and append a
"## Analisis LLM" section.

In that section, include:
- Overall summary.
- One bullet per package with local version, latest version, update availability,
  remote change, status, errors, source/release links, update command, and
  recommendation.
- Changelog impact from the JSON report when present.
- "No changelog impact found" when no changelog impact exists in the JSON.
- Package-specific precautions supported by the JSON report.

Do not infer from unrelated sources.
Do not install, update, or modify dependencies.
Do not open PRs or create commits.

After writing the Markdown analysis, post a short chat summary with the Markdown
and JSON report paths.

Required run constraints:

• Read only library-watch/watchlist.yml.
• Do not discover related packages, unconfigured skills, repos, URLs, or tools.
• Do not install, update, or modify dependencies.
• Do not open PRs or create commits.
• Let the script write raw monitor output under library-watch/state.json, library-watch/runs/, and library-watch/.cache/.
• Let the LLM modify only the generated Markdown report for the current run when adding analysis.

Generic cron example:

0 9 */2 * * cd /path/to/repo && python3 library-watch/scripts/check_versions.py

Generic launchd setup should do the same two things: set the repository root as the working directory and run python3 library-watch/scripts/check_versions.py.

Watchlist entry format

Add one library/tool per entry:

{
  "id": "short-lowercase-id",
  "display_name": "Human Name",
  "source_type": "github_release",
  "source": "owner/repo",
  "local_check": {
    "command": "tool --version"
  },
  "update_command": null,
  "notes": "Why this should be monitored"
}

Rules:

• source must be exact. Do not guess repos, package names, or URLs.
• source_type must be github_release, npm, or NEEDS_SOURCE.
• local_check.command must be read-only.
• update_command is optional and never runs automatically.