Add uploader scripts and docs

INSTALL.md

@@ -0,0 +1,124 @@
+# Installation
+
+## Prerequisites
+
+### 1. Python 3
+
+macOS includes Python 3. Verify with:
+
+```bash
+python3 --version
+```
+
+If missing: `brew install python`
+
+### 2. rsync
+
+macOS ships rsync 2.6.9 (2006), which has bugs with path handling. Install the current version:
+
+```bash
+brew install rsync
+```
+
+### 3. SSH key access to the remote host
+
+The uploader runs unattended, so it must be able to reach the remote host without a password. This means SSH key-based authentication needs to be in place before you install.
+
+If you don't already have an SSH key, generate one:
+
+```bash
+ssh-keygen -t ed25519
+```
+
+Then authorize it on the remote host:
+
+```bash
+ssh-copy-id filez@10.10.8.1
+```
+
+Confirm the connection works without any password prompt before continuing:
+
+```bash
+ssh filez@10.10.8.1 echo ok
+```
+
+If your key lives somewhere other than the default location (`~/.ssh/id_rsa` or `~/.ssh/id_ed25519`), set the `ssh_key_path` field in `downloads_uploader_config.json` to its full path.
+
+---
+
+## Install
+
+```bash
+cd ~/Downloads/uploader
+./downloads_uploader_install.sh install
+```
+
+This will:
+1. Create `~/.local/bin/downloads-uploader` (a named symlink to `python3` so macOS permission dialogs show a friendly name)
+2. Write `~/Library/LaunchAgents/com.user.downloads-uploader.plist`
+3. Load the agent — it runs immediately and then every 5 minutes
+
+**macOS may prompt for network/file access permissions** the first time. Allow them.
+
+---
+
+## Configure
+
+Open `downloads_uploader_config.json` and set your remote destination:
+
+```json
+{
+  "remote_destination": "user@your-host:/path/to/remote/dir/",
+  "ssh_key_path": "",
+  "ssh_port": 22
+}
+```
+
+Then trigger a fresh run:
+
+```bash
+./downloads_uploader_install.sh run
+```
+
+Check the output:
+
+```bash
+./downloads_uploader_install.sh status
+```
+
+---
+
+## Uninstall
+
+```bash
+./downloads_uploader_install.sh uninstall
+```
+
+This stops and removes the launchd agent and the symlink. Config, logs, and state files are left in place.
+
+---
+
+## Troubleshooting
+
+**"rsync not found"**
+```bash
+brew install rsync
+```
+
+**SSH connects but `find` fails on remote**
+The script uses GNU `find -printf`, which requires Linux. BSD/macOS remotes are not supported on the remote side.
+
+**Files keep re-uploading**
+Size mismatch between local and remote. Check that the remote filesystem isn't silently modifying files (e.g. a torrent client moving them). You can inspect `.uploader_state.json` for the last recorded sizes.
+
+**Agent not running after reboot**
+Verify the plist is in `~/Library/LaunchAgents/` and loaded:
+```bash
+launchctl list | grep downloads-uploader
+```
+If missing, re-run `./downloads_uploader_install.sh install`.
+
+**See full logs**
+```bash
+tail -f ~/Downloads/uploader/uploader_log.txt
+```