# rclone-jav — Install Guide

End-to-end setup for a fresh PC. Tested on Windows 11 + Brave Stable. Should also work for Chrome with minor path tweaks.

> **PC2 / Staging note:** Paths below use `D:\DEV\Extensions\Production\rclone-jav\`. On the Staging PC, substitute `Production` → `Staging` throughout.

---

## Prerequisites

1. **Python 3.9+** on PATH. Verify:
   ```
   python --version
   ```
   Note the install location (e.g. `C:\Python314\python.exe`). Needed in step 6.

2. **rclone** on PATH with your remotes configured (`rclone config`). Verify:
   ```
   rclone version
   rclone lsf <your-remote>: -R --include "*IPZZ*"   # sanity check
   ```

   **If "rclone not found" in a fresh PowerShell** despite being installed: Windows Terminal sometimes caches the old PATH across new pwsh sessions. Quick fix for the current session:
   ```powershell
   $env:Path += ';C:\Programs\rclone'    # or wherever rclone.exe lives
   rclone version
   ```
   Permanent fix: close Windows Terminal completely (all windows, not just tabs) and reopen — fresh pwsh will inherit the registered user PATH. If still missing, sign out/in once.

3. **Brave** (Stable, Beta, Dev, or Nightly — install registers all four channels).

4. **rich** (Python package, used by `rc-jav.py`):
   ```
   pip install rich
   ```

---

## Step 1 — Place the files

Copy both project folders:

```
D:\DEV\Project\rclone-jav\     ← rc-jav.py + cache.json + config.json + wincatalog\
D:\DEV\Extensions\Production\rclone-jav\     ← manifest + host\
```

`rcjav-host.bat` is now portable — it uses Windows' `py` launcher or falls back to `python` on PATH. **No per-machine Python path edits needed** as long as Python is on PATH.

If you put the project folder elsewhere than `D:\DEV\Project\rclone-jav`, you'll either:
- Edit the `RC_JAV` constant at the top of `D:\DEV\Extensions\Production\rclone-jav\host\rcjav-host.py`, OR
- Set it via the extension's Options → **Setup & Transfer → rc-jav script path** (works without editing files).

---

## Step 2 — Configure rc-jav defaults

Edit `D:\DEV\Project\rclone-jav\config.json` (create if missing):

```json
{
  "default_target": ["cq:personal-files/JAV"],
  "default_source": [],
  "default_catalog": []
}
```

Or set interactively:

```
cd D:\DEV\Project\rclone-jav
python rc-jav.py --target cq:personal-files/JAV --save
```

Verify:

```
python rc-jav.py --search IPZZ-860 -q --basic
```

Should return a hit in ~1–2 seconds.

---

## Step 3 — Load the Brave extension

1. Open `brave://extensions`.
2. Toggle **Developer mode** ON (top-right).
3. Click **Load unpacked**.
4. Pick `D:\DEV\Extensions\Production\rclone-jav` (the folder containing `manifest.json`).
5. **Copy the Extension ID** shown on the card. Example: `gnimjpgbgehbefdkdjodcimefdedgeho`.

---

## Step 4 — Register the native messaging host

Easiest: double-click `D:\DEV\Extensions\Production\rclone-jav\host\register-host.bat`. It prompts for the ID and runs the installer.

Or manually in PowerShell (any window — script self-elevates):

```powershell
cd D:\DEV\Extensions\Production\rclone-jav\host
.\install-host.ps1 -ExtensionId <paste-the-extension-id>
```

UAC will prompt — click **Yes**. The script writes:

- **Manifest:** `D:\DEV\Extensions\Production\rclone-jav\host\com.rcjav.host.json` (UTF-8 no BOM)
- **Registry (HKLM + HKCU):**
  - `\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.rcjav.host`
  - `\Software\Google\Chrome\NativeMessagingHosts\com.rcjav.host`
  - `\Software\WOW6432Node\Google\Chrome\NativeMessagingHosts\com.rcjav.host`
  - `\Software\Chromium\NativeMessagingHosts\com.rcjav.host`

HKLM is **required** — Brave on Windows often ignores HKCU. The script writes both as belt-and-suspenders.

Verify registry:

```powershell
reg query "HKLM\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.rcjav.host"
```

Should print `(Default)  REG_SZ  D:\DEV\Extensions\Production\rclone-jav\host\com.rcjav.host.json`.

---

## Step 5 — Fully restart Brave

Closing windows is not enough. Brave caches NM host registrations at process startup.

```powershell
Get-Process brave | Stop-Process -Force
```

Or Task Manager → kill every `brave.exe`. Then reopen Brave.

---

## Step 6 — Verify

1. Click the rclone-jav toolbar icon.
2. Popup opens, auto-runs a check on the current tab.
3. Click **Ping host**. Expect green banner: `host ok: 0.1.0`.

If green, you're done.

---

## Step 7 — Choose triggers (optional)

Click the gear icon in the popup (or right-click extension → Options) to enable:

- Auto-check every page load
- Auto-check on listed JAV sites (configurable host patterns)
- Toolbar icon popup auto-check
- Right-click context menu
- Keyboard shortcut (default `Alt+J`, rebind at `brave://extensions/shortcuts`)

Enable any combination.

---

## Troubleshooting

**Popup shows "host unreachable" / "Specified native messaging host not found":**
- Did UAC prompt complete? Re-run `install-host.ps1`.
- `reg query "HKLM\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.rcjav.host"` must return the manifest path. If empty: install script failed silently.
- Manifest file must exist at the registered path AND be valid JSON AND have **no BOM**. Check: `python -c "import json; json.load(open(r'D:\DEV\Extensions\Production\rclone-jav\host\com.rcjav.host.json'))"` — no error = valid.
- Fully kill all `brave.exe`, then reopen.
- `allowed_origins` in the manifest must match the current extension ID. If you reloaded the extension and the ID changed, re-run `install-host.ps1`.

**Popup shows "host error: ...":**
- Host launched but Python died. Read `D:\DEV\Extensions\Production\rclone-jav\host\logs\rcjav-host-stderr.log`.
- Common cause: wrong `python.exe` path in `rcjav-host.bat`, or wrong `RC_JAV` path in `rcjav-host.py`.

**Badge stays `?`:**
- Page title has no JAV ID. Extension regex: `[A-Z]{2,}-?[0-9]{2,5}`.

**Badge stays `!`:**
- Host returned non-zero exit code. Check `host\logs\rcjav-host-stderr.log` and `host\logs\rcjav-host.log`.

**Search returns no hits but the file exists:**
- Cache may be stale. Run `python rc-jav.py --scan` to refresh, or pass `--quick` (extension does this by default).

**Brave verbose logging for deep debug:**
```powershell
& "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" --enable-logging=stderr --vmodule="*native_messaging*=2" 2>&1 | Tee-Object D:\brave-nm.log
# Click ping in extension, then:
Select-String -Path D:\brave-nm.log -Pattern "native|rcjav|com\.rc" -Context 0,2
```

`Can't find manifest for native messaging host com.rcjav.host` = registry not seen → re-run installer + restart Brave.

---

## Uninstall

```powershell
# Remove registry entries (admin)
$keys = @(
  'HKLM:\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.rcjav.host',
  'HKLM:\Software\Google\Chrome\NativeMessagingHosts\com.rcjav.host',
  'HKLM:\Software\WOW6432Node\Google\Chrome\NativeMessagingHosts\com.rcjav.host',
  'HKLM:\Software\Chromium\NativeMessagingHosts\com.rcjav.host',
  'HKCU:\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\com.rcjav.host',
  'HKCU:\Software\Google\Chrome\NativeMessagingHosts\com.rcjav.host',
  'HKCU:\Software\Chromium\NativeMessagingHosts\com.rcjav.host'
)
foreach ($k in $keys) { Remove-Item -Path $k -Force -ErrorAction SilentlyContinue }
```

Then remove the extension at `brave://extensions`, and delete `D:\DEV\Extensions\Production\rclone-jav\`.

---

## Key gotchas learned the hard way

| Gotcha | Symptom | Fix |
|---|---|---|
| UTF-8 BOM in manifest | "Specified native messaging host not found." | Write file with `[System.Text.UTF8Encoding]::new($false)` |
| HKCU-only registration | Same error, even with valid manifest | Register HKLM (admin) |
| Buffered Python stdio | Host launches but Brave times out | `python -u` in .bat |
| Text-mode stdio on Windows | First message corrupts immediately | `msvcrt.setmode(..., os.O_BINARY)` in host script |
| stderr on stdout | Garbage bytes break length prefix | Redirect stderr to file in .bat |
| Extension reload != Brave restart | Stale NM cache | Kill all `brave.exe` then reopen |
| Extension ID changes on reload | allowed_origins mismatch | Re-run `install-host.ps1` (or `register-host.bat`) with new ID |
| em-dashes (—) in .ps1 file + Windows PS 5.1 + no BOM | `Missing closing '}'` parse errors at random lines | Strip em-dashes (replace with `-`), or save .ps1 with UTF-8 BOM, or invoke via `pwsh` instead of `powershell.exe` |