# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this project is

`ping-rss` is a Python CLI tool that accelerates website indexation by pinging RSS aggregators, Google PubSubHubbub, IndexNow, and Google Search Console URL Inspection API. Designed for 20+ sites managed via a single YAML config.

## Commands

This tool lives inside the `Scripts/` monorepo at `python/ping-rss/`. Use `uv` from the monorepo root.

```bash
# Install / sync deps
uv sync --directory python/ping-rss

# Run via entry point (from monorepo root)
uv run --directory python/ping-rss ping-rss check                          # Validate config
uv run --directory python/ping-rss ping-rss sites                          # List configured sites
uv run --directory python/ping-rss ping-rss ping <site-slug>               # Ping all services for a site
uv run --directory python/ping-rss ping-rss ping --all                     # Ping all sites
uv run --directory python/ping-rss ping-rss ping <slug> --only xmlrpc,pubsub  # Specific services only
uv run --directory python/ping-rss ping-rss ping <slug> --urls https://...    # Submit specific URLs
uv run --directory python/ping-rss ping-rss ping <slug> --dry-run          # Preview without executing

# Run via module
uv run --directory python/ping-rss python -m ping_rss ping <site-slug>
```

## Architecture

Four independent pingers orchestrated by a parallel runner:

- **xmlrpc_ping** — `weblogUpdates.ping` via stdlib `xmlrpc.client`, parallel across services with ThreadPoolExecutor
- **pubsubhubbub** — POST to Google's WebSub hub via stdlib `urllib.request`
- **indexnow** — JSON POST to IndexNow API (Bing/Yandex/Naver), batch up to 10k URLs
- **gsc** — Google Search Console URL Inspection API via `google-auth` + `googleapiclient`, 200/day quota

`runner.py` executes all enabled pingers in parallel and collects results. `cli.py` handles argument parsing and dispatches to the runner. `config.py` loads `sites.yaml` with defaults merging (global defaults + per-site overrides).

## Config

`sites.yaml` at project root or `~/.config/ping-rss/sites.yaml`. Each site needs: `name`, `feed_url`, `site_url`. Optional: `indexnow_key`, `ping_services` override, `pubsubhubbub_hub` override.

GSC requires a Google service account JSON file configured in `google.service_account_json`.

## Dependencies

Only 3 external: `pyyaml`, `google-auth`, `google-api-python-client`. Everything else is stdlib.