feat: add AdGuardHome CLI harness — first REST API service harness

.gitignore

@@ -32,6 +32,7 @@
 !/anygen/
 !/zoom/
 !/drawio/
+!/adguardhome/
 
 # Step 5: Inside each software dir, ignore everything (including dotfiles)
 /gimp/*
@@ -56,6 +57,8 @@
 /zoom/.*
 /drawio/*
 /drawio/.*
+/adguardhome/*
+/adguardhome/.*
 
 # Step 6: ...except agent-harness/
 !/gimp/agent-harness/
@@ -69,6 +72,7 @@
 !/anygen/agent-harness/
 !/zoom/agent-harness/
 !/drawio/agent-harness/
+!/adguardhome/agent-harness/
 
 # Step 7: Ignore build artifacts within allowed dirs
 **/__pycache__/

adguardhome/agent-harness/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+.fastembed_cache/
+.leann/
+*.egg-info/
+dist/
+build/

adguardhome/agent-harness/ADGUARDHOME.md

@@ -0,0 +1,66 @@
+# AdGuardHome - CLI Harness SOP
+
+## Overview
+
+AdGuardHome is a DNS-based ad blocker and privacy protection server written in Go.
+It exposes a REST HTTP API with 58 endpoints organized in 14 tag groups, secured with HTTP Basic Auth.
+
+**Real software:** The running AdGuardHome HTTP API (not a binary to invoke directly).
+**CLI role:** Generate structured commands - call the real API - verify responses.
+
+## Architecture
+
+- **API base:** `http://<host>:<port>/control/`
+- **Auth:** HTTP Basic Auth (`Authorization: Basic base64(user:pass)`)
+- **Port:** 3000 by default
+- **OpenAPI spec:** `openapi/openapi.yaml` in the AdGuardHome source
+
+## API Tag Groups
+
+| Group | Description | Key Endpoints |
+|-------|-------------|---------------|
+| `global` | Server settings and controls | `/status`, `/version`, `/restart` |
+| `filtering` | Rule-based filtering | `/filtering/status`, `/filtering/add_url`, `/filtering/remove_url` |
+| `blocked_services` | Block service categories | `/blocked_services/get`, `/blocked_services/set` |
+| `clients` | Known clients | `/clients`, `/clients/add`, `/clients/delete` |
+| `stats` | DNS query statistics | `/stats`, `/stats_reset`, `/stats_config` |
+| `log` | Query log | `/querylog`, `/querylog_config`, `/querylog_clear` |
+| `dhcp` | Built-in DHCP server | `/dhcp/status`, `/dhcp/leases`, `/dhcp/set_config` |
+| `rewrite` | DNS rewrites | `/rewrite/list`, `/rewrite/add`, `/rewrite/delete` |
+| `parental` | Adult content blocking | `/parental/status`, `/parental/enable`, `/parental/disable` |
+| `safebrowsing` | Malware/phishing blocking | `/safebrowsing/status`, `/safebrowsing/enable`, `/safebrowsing/disable` |
+| `safesearch` | Safe search enforcement | `/safesearch/status`, `/safesearch/enable`, `/safesearch/disable` |
+| `tls` | HTTPS/DoH/DoT settings | `/tls/status`, `/tls/configure`, `/tls/validate` |
+
+## CLI Command Map
+
+```
+cli-anything-adguardhome
+├── config show / save / test
+├── server status / version / restart
+├── filter list / add / remove / enable / disable / refresh / status / toggle
+├── blocking parental status/enable/disable
+│          safebrowsing status/enable/disable
+│          safesearch status/enable/disable
+├── blocked-services list / set
+├── clients list / add / remove / show
+├── stats show / reset / config
+├── log show / config / clear
+├── rewrite list / add / remove
+├── dhcp status / leases / add-static / remove-static
+└── tls status
+```
+
+## Connection Config
+
+Settings resolved in order:
+1. CLI flags (`--host`, `--port`, `--username`, `--password`)
+2. Environment vars (`AGH_HOST`, `AGH_PORT`, `AGH_USERNAME`, `AGH_PASSWORD`)
+3. Config file (`~/.config/cli-anything-adguardhome.json`)
+4. Defaults: `localhost:3000`
+
+## Testing Strategy
+
+- **Unit tests:** Mock HTTP calls via `unittest.mock` - no real AdGuardHome needed
+- **E2E tests:** Spin up `adguard/adguardhome` via Docker on port 3001 for isolation
+- **Subprocess tests:** `_resolve_cli("cli-anything-adguardhome")` tests the installed CLI binary

adguardhome/agent-harness/cli_anything/adguardhome/README.md

@@ -0,0 +1,71 @@
+# cli-anything-adguardhome
+
+CLI harness for AdGuardHome - control your ad blocker from the command line or via agents.
+
+## Prerequisites
+
+AdGuardHome must be running. Install:
+
+```bash
+# Linux - native
+curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
+
+# Docker
+docker run --name adguardhome -p 3000:3000 adguard/adguardhome
+```
+
+## Installation
+
+```bash
+cd agent-harness
+pip install -e .
+cli-anything-adguardhome --help
+```
+
+## Configuration
+
+```bash
+export AGH_HOST=localhost
+export AGH_PORT=3000
+export AGH_USERNAME=admin
+export AGH_PASSWORD=secret
+
+# Or save to config file
+cli-anything-adguardhome --host localhost --port 3000 --username admin --password secret config save
+```
+
+## Usage
+
+```bash
+# Interactive REPL (default)
+cli-anything-adguardhome
+
+# One-shot commands
+cli-anything-adguardhome server status
+cli-anything-adguardhome filter list
+cli-anything-adguardhome --json stats show
+
+# Filtering
+cli-anything-adguardhome filter add --url https://somehost.com/list.txt --name "My List"
+cli-anything-adguardhome filter refresh
+
+# DNS rewrites
+cli-anything-adguardhome rewrite add --domain "myserver.local" --answer "192.168.1.50"
+cli-anything-adguardhome rewrite list
+
+# Clients
+cli-anything-adguardhome clients add --name "My PC" --ip 192.168.1.100
+
+# Stats
+cli-anything-adguardhome stats show
+cli-anything-adguardhome stats reset
+```
+
+## Tests
+
+```bash
+cd agent-harness
+python3 -m pytest cli_anything/adguardhome/tests/test_core.py -v
+python3 -m pytest cli_anything/adguardhome/tests/test_full_e2e.py -v -s
+CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything/adguardhome/tests/ -v -s
+```

adguardhome/agent-harness/cli_anything/adguardhome/__main__.py

@@ -0,0 +1,5 @@
+"""Enable python -m cli_anything.adguardhome"""
+from cli_anything.adguardhome.adguardhome_cli import main
+
+if __name__ == "__main__":
+    main()