admin
228 lines
8.3 KiB
Markdown
228 lines
8.3 KiB
Markdown
# 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` |
|