git:20260730.8701183 to git:20260814.64aecf3

0 added, 26 removed. Audit A to A.

# abx-dl Agent Guide

`abx-dl` is the standalone downloader/extractor CLI that runs ArchiveBox plugin hooks without a full ArchiveBox collection. Keep this repo on `main`.

## Shared Standards

- Use `uv` and `uv run` for Python commands. Do not use system `python`, direct `.venv/bin/python`, or `pip` commands.

- Prefer existing repo patterns, helper APIs, fixtures, scripts, and command surfaces.

- Keep edits focused and minimal. Do not add wrappers, shims, aliases, or extra abstraction layers unless the current code path requires them.

- Do not weaken assertions, skip tests, xfail tests, or accept flaky behavior.

- No mocks, monkeypatches, fakes, simulated handlers, fake binaries, fake hooks, fake buses, or direct shortcuts around user-facing flows.

- Tests and verification should use real CLI commands, real hooks, real installs, real subprocesses, real DB/config rows where present, real files, real URLs or `pytest-httpserver`, and existing fixtures.

- Assertions must verify real correctness: exit codes, returned values, event records, filesystem contents, field values, output files, and side effects.

- Start behavior fixes with a red failing test when a test is requested or practical.

- Trace root causes from observed behavior. Do not paper over failures with retries, wider timeouts, broad fallbacks, or looser assertions.

- Read `README.md` for the full CLI, config, plugin, and release surface.

## Development Setup

<!--

```bash

export UV_PROJECT_ENVIRONMENT="$(mktemp -d)/.venv"

unset VIRTUAL_ENV

```

-->

```bash

set -Eeuo pipefail

uv sync

help_output="$(uv run abx-dl --help)"

grep -q 'Usage:' <<<"$help_output"

```

## Plugin Inspection

```bash

set -Eeuo pipefail

plugin_info="$(uv run abx-dl plugins wget)"

grep -q 'WGET_BINARY=wget' <<<"$plugin_info"

grep -q 'on_Snapshot__06_wget' <<<"$plugin_info"

```

- Docker:

-

- ```bash

- set -Eeuo pipefail

- output_dir="$(mktemp -d)"

- image="${ABXDL_IMAGE:-archivebox/abx-dl:latest}"

- trap 'rm -rf "$output_dir"' EXIT

- docker run --rm \

- --env OUTPUT_UID="$(id -u)" \

- --env OUTPUT_GID="$(id -g)" \

- --volume "$output_dir:/out" \

- --entrypoint bash \

- "$image" \

- -c 'set -Eeuo pipefail

- cleanup() { chown -R "$OUTPUT_UID:$OUTPUT_GID" /out; }

- trap cleanup EXIT

- /venv/bin/abx-dl "$@"' \

- -- --no-install --max-urls=1 --plugins=title,wget 'https://example.com'

- test -s "$output_dir/index.jsonl"

- test -s "$output_dir/title/title.txt"

- test -s "$output_dir/wget/example.com/index.html"

- grep -q 'Example Domain' "$output_dir/title/title.txt"

- grep -q 'Example Domain' "$output_dir/wget/example.com/index.html"

- ```

## Basic Usage

```text

uv run abx-dl dl --plugins=title,wget,screenshot,pdf 'https://example.com'

uv run abx-dl dl --output=html,json,txt,pdf,image 'https://example.com'

uv run abx-dl install wget ytdlp chrome

uv run abx-dl config

uv run abx-dl config --get TIMEOUT

```

## Verification

Use targeted live user-facing commands:

```bash

set -Eeuo pipefail

tmpdir="$(mktemp -d)"

cd "$tmpdir"

uv run --project /path/to/abx-dl abx-dl dl --plugins=chrome,consolelog,headers,wget 'https://example.com'

test -s index.jsonl

```

The main CI workflow runs the exhaustive repository suite and the separate Prek

job runs every hook.

Background hook scheduling is based only on `bg` vs `fg`; filename words like

`daemon` and `finite` are human hints only. Background hooks advance the

scheduler on their first stdout line or successful completion; that first stdout

line must mean the hook is ready for the next hook to launch, and non-ready

diagnostics belong on stderr.