podpull: Instructions file for Claude Code

CLAUDE.md

Guidance for AI coding agents (and humans) working in the podpull repository. This is the canonical agent guide; AGENTS.md points here.

What this is

podpull is a small command-line tool that downloads a specific podcast episode's audio from an Apple Podcasts show/episode, a raw RSS feed, or a xiaoyuzhou / 小宇宙 episode link.

The core idea: Apple Podcasts hosts no audio — it points at each show's RSS feed, where every episode carries a direct <enclosure> URL. podpull walks that chain and downloads the file. No login, no DRM.

Python ≥ 3.9. Published on PyPI (pipx install podpull) and a Homebrew tap (brew install xiaoleiy/tap/podpull).

Layout

src/podpull/
  __init__.py        # __version__ lives here
  __main__.py        # `python -m podpull`
  core.py            # resolve/parse/search/select/download — PURE STDLIB, no third-party imports
  cli.py             # argparse commands + ALL UI (rich, questionary, rich-argparse)
  skills.py          # `podpull skills` — installs agent integrations
  serve/             # `podpull serve` — stdlib HTTP metadata API + static UI
  integrations/      # bundled skill/command/rule files (packaged as wheel data)
tests/               # test_core.py, test_cli.py, test_skills.py  (pytest, no network)
docs/                # index.html (Aurora landing), HOSTING.md, icon.svg, demo.tape/demo.gif
public/              # generated by scripts/sync_web_public.py for Vercel (do not hand-edit)
api/                 # Vercel Python metadata gateway (wraps serve.handle_api)
scripts/             # sync_web_public.py — docs/ + serve/static → public/
vercel.json          # podpull.xiaolei.work deploy config
.github/workflows/   # ci.yml, publish.yml (PyPI), release.yml (Homebrew tap bump)

Load-bearing invariants — do NOT break these

1. core.py stays dependency-free. Only the Python standard library. All third-party deps (rich, questionary, rich-argparse) live in cli.py. Network/parse/download logic is pure stdlib so it's easy to test and audit. If you need a UI concern in core, pass a callback (see download_url(..., on_progress=…)) rather than importing rich.
2. stdout = machine output, stderr = humans. Downloaded file paths print to stdout; spinners, tables, progress bars, and messages go to stderr (rich Console(stderr=True)). Keep it that way — people pipe/capture stdout.
3. Interactive picker vs. scripting. podpull get <show> with no selector opens the questionary multi-select picker only when stdin+stderr are a TTY and --no-input isn't set; otherwise it prints a listing + hint and exits non-zero (never hangs).
4. Cloud-/Windows-safe filenames. core.safe_filename NFKC-folds, drops emoji/symbols and control chars, strips OS-forbidden + full-width chars, trims edges, caps at 120, and avoids Windows reserved device names (CON, NUL, …). Preserve this when touching naming.
5. Browser User-Agent. core.UA is a plain browser UA on purpose — xiaoyuzhou's CDN (feed.xyzfm.space) returns 403 to identifiable tool UAs. Don't "brand" it back.
6. All text file I/O is explicit encoding="utf-8". Windows defaults to cp1252 and will raise on CJK otherwise (audio writes are binary — that's fine).
7. Episodes land in a per-show sub-folder (<out>/<show name>/, default --out is the current working directory). Pasted single-episode links (no show title) still land directly in --out.