abx-dl CLAUDE.md

Claude Code Instructions for abx-dl

Use AGENTS.md as the canonical repository guide. Keep this checkout on main, use uv for Python commands, and exercise real CLI, plugin, subprocess, network, and filesystem paths in tests. Do not add skips, xfails, retries, fake hooks, fake binaries, fake buses, or fallback binary resolution.

Development setup

set -Eeuo pipefail
uv sync --locked --dev --no-sources
help_output="$(uv run --no-sync --no-sources abx-dl --help)"
grep -q 'Usage:' <<<"$help_output"

Inspect the installed plugin surface

set -Eeuo pipefail
plugin_info="$(uv run --no-sync --no-sources abx-dl plugins wget)"
grep -q 'WGET_BINARY=wget' <<<"$plugin_info"
grep -q 'on_Snapshot__35_wget' <<<"$plugin_info"

Verification

The normal CI workflow assigns every repository test file exactly once across Linux, macOS, and every supported Python minor version. It also runs every non-Docker documentation snippet and a real crawl across every Snapshot hook from the pinned abx-plugins release. The Docker workflow builds and tests both amd64 and arm64 images and runs every snippet marked docker_required.

Run the repository's complete static verification before publishing changes:

set -Eeuo pipefail
uv run --no-sync --no-sources prek run --all-files

Releases

Releases are automatic from main. Bump the version and its lockfile, commit, and push. The release workflow waits for the exact commit's test workflow, creates the matching GitHub release and tag, waits for the exact Docker build, and publishes the package through PyPI trusted publishing. Do not create or push tags locally.

Architecture

• Plugin discovery comes from the installed abx-plugins package or the explicit ABX_PLUGINS_DIR override.
• Required binaries are emitted as BinaryRequestEvent records and resolved only by abxpkg; host binaries are considered before managed providers.
• Resolved host and managed binaries are projected into ABXPKG_LIB_DIR/env/bin. ABXPKG_LIB_DIR/bin is only a human convenience surface and must never be used programmatically.
• Crawl setup and snapshot hooks run through the unified event state machine. Chrome readiness uses its plugin-owned file mechanism rather than a generic bus-level readiness event.