deploy: track the host-side Transmission hook wrapper

deploy/README.md

@@ -0,0 +1,45 @@
+# Host-side deploy artifacts
+
+Files here run on the Docker **host**, not inside the faucet container, so they
+are not copied in by the Dockerfile and have to be installed by hand. They live
+in git so a host rebuild doesn't silently lose them.
+
+## cascade-hook-wrapper.sh
+
+Transmission's completion hook. Transmission runs on the host and writes to
+`/mnt/nas/torrents`; the container sees the same NAS path as `/downloads`. The
+wrapper translates between the two and calls `faucet.hook` inside the container
+via `docker exec`.
+
+Install:
+
+```bash
+sudo install -m 0755 -o root -g root \
+  deploy/cascade-hook-wrapper.sh /opt/cascade-hook-wrapper.sh
+```
+
+The mode matters. Transmission execs this script directly, so a copy without
+the execute bit fails silently at completion time — and files committed through
+the GitHub API land as `644`, so don't just `cp` it.
+
+Then, with the daemon **stopped** (transmission rewrites `settings.json` on
+exit and will clobber edits made while it's running):
+
+```bash
+sudo systemctl stop transmission-daemon
+sudo -e /etc/transmission-daemon/settings.json
+```
+
+```json
+"script-torrent-done-enabled": true,
+"script-torrent-done-filename": "/opt/cascade-hook-wrapper.sh",
+```
+
+```bash
+sudo systemctl start transmission-daemon
+```
+
+Verify by completing a small torrent and checking that faucet logged the hook
+firing. If nothing happens, check in this order: the execute bit, the path in
+`settings.json`, and whether the `faucet` container is actually named `faucet`
+(the wrapper hardcodes it).

deploy/cascade-hook-wrapper.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# cascade-hook-wrapper.sh — host-side Transmission completion hook.
+#
+# Transmission runs on the host and now downloads to the NAS at
+# /mnt/nas/torrents. The faucet container sees that same NAS path mounted at
+# /downloads. This translates the host path to the container's view and invokes
+# faucet's hook inside the container via docker exec.
+#
+# Install to /opt/cascade-hook-wrapper.sh, mode 755, root-owned.
+#
+# Wire it in /etc/transmission-daemon/settings.json (daemon stopped first):
+#   "script-torrent-done-enabled": true,
+#   "script-torrent-done-filename": "/opt/cascade-hook-wrapper.sh",
+set -uo pipefail
+CONTAINER="faucet"
+HOST_DL="/mnt/nas/torrents"
+CONTAINER_DL="/downloads"
+# Translate the completed path into the container's view.
+host_path="${TR_TORRENT_DIR:-}/${TR_TORRENT_NAME:-}"
+container_path="${host_path/$HOST_DL/$CONTAINER_DL}"
+# Hand off to faucet's hook inside the container. REMOVE_ON_COMPLETE and
+# MEDIASORT_MODE come from the container's own env (the Portainer stack).
+exec docker exec \
+  -e FAUCET_PATH="$container_path" \
+  -e FAUCET_NAME="${TR_TORRENT_NAME:-}" \
+  -e FAUCET_ID="${TR_TORRENT_ID:-}" \
+  "$CONTAINER" python -m faucet.hook