Initial snapshot before step 6 options.js split
This commit is contained in:
admin
@@ -0,0 +1,37 @@
|
||||
# Stable Extension ID
|
||||
|
||||
Chrome and Brave derive an extension ID from the extension public key. If the
|
||||
key changes, the extension ID changes too.
|
||||
|
||||
Why this matters for rclone-jav:
|
||||
|
||||
- `chrome.storage.sync` settings are scoped to the extension ID.
|
||||
- The native messaging host manifest authorizes specific extension IDs in
|
||||
`allowed_origins`.
|
||||
- Moving or reloading an unpacked extension without a fixed key can make settings
|
||||
appear to vanish and can break native messaging.
|
||||
|
||||
## Recommended workflow
|
||||
|
||||
1. Export settings from Options -> Backup before changing install paths.
|
||||
2. Keep Production loaded from a stable folder path.
|
||||
3. For a permanently stable unpacked ID, add a fixed Chrome extension public key
|
||||
to `manifest.json` under the `key` field.
|
||||
4. After the ID changes intentionally, update the native host manifest
|
||||
`allowed_origins` and re-register the host.
|
||||
5. Import the settings backup.
|
||||
|
||||
## Packed extension workflow
|
||||
|
||||
If you pack the extension as a `.crx`, save the generated `.pem` private key.
|
||||
Packing future versions with the same `.pem` produces the same extension ID.
|
||||
|
||||
Do not lose or share the `.pem`; it controls the extension identity.
|
||||
|
||||
## Unpacked extension workflow
|
||||
|
||||
For unpacked installs, use the public key derived from the `.pem` as
|
||||
`manifest.json`'s `key` value. The value must be the Chrome extension public key
|
||||
format, not an arbitrary string.
|
||||
|
||||
Same manifest key = same extension ID.
|
||||
+227
@@ -0,0 +1,227 @@
|
||||
# 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` |
|
||||
@@ -0,0 +1,79 @@
|
||||
# rclone-jav
|
||||
|
||||
Brave extension that extracts JAV IDs from the active page and checks them against your local rc-jav library via a native-messaging Python host.
|
||||
|
||||
> **Setup:** see [`INSTALL.md`](./INSTALL.md). This file documents how it works once installed.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Brave tab title (e.g. "MILK-257")
|
||||
─► content/background script extracts ID
|
||||
─► chrome.runtime.connectNative("com.rcjav.host")
|
||||
─► rcjav-host.bat → rcjav-host.py
|
||||
─► python rc-jav.py --search MILK-257 --basic --no-color
|
||||
─► result back through the port
|
||||
─► popup / notification / badge
|
||||
```
|
||||
|
||||
Long-lived port: Brave keeps the host process alive while the connection is open, so subsequent lookups don't pay Python startup cost.
|
||||
|
||||
## Triggers (all available, enable any combination in Options)
|
||||
|
||||
| Trigger | Behavior |
|
||||
|---|---|
|
||||
| **Auto-check every page load** | Fires `chrome.tabs.onUpdated`. Badge shows hit count or `?` when no JAV ID detected. Noisy. |
|
||||
| **Auto-check on known JAV sites** | Same as above but gated by host patterns (e.g. `*.javdb.com`). |
|
||||
| **Toolbar icon popup** | Click the icon → popup can run a check on the active tab. The Scan Behavior toggle gates popup auto-check. |
|
||||
| **Right-click context menu** | "rclone-jav: check this page". Shows a desktop notification. |
|
||||
| **Keyboard shortcut (Alt+J)** | Rebind at `brave://extensions/shortcuts`. |
|
||||
|
||||
Enable them all to compare — they don't conflict.
|
||||
|
||||
## ID extraction
|
||||
|
||||
Uses site adapters, URL text, and the page title plus ID normalizers. Common title forms include:
|
||||
- `MILK-257` → `MILK-257`
|
||||
- `MILK257` → `MILK-257`
|
||||
- `Some site - MILK-257 [4K]` → `MILK-257`
|
||||
|
||||
## Search behavior
|
||||
|
||||
By default the extension passes `--quick` to rc-jav (single-ID live `rclone lsjson --include`, ~1–2s, fresh data, no cache). Uncheck **Use --quick mode** in options to use the cache (faster on warm cache, may be stale).
|
||||
|
||||
## Files
|
||||
|
||||
```
|
||||
manifest.json MV3 manifest
|
||||
background.js service worker, native-messaging port, triggers
|
||||
content.js page extraction, element picker, and in-page overlays
|
||||
popup.html / .css / .js click-the-icon UI
|
||||
options.html / .js trigger toggles + known-site patterns
|
||||
icons/ extension icons
|
||||
host/
|
||||
rcjav-host.py native messaging host (length-prefixed JSON)
|
||||
rcjav-host.bat shim so the manifest path is stable
|
||||
install-host.ps1 writes the manifest into Brave's NM dir
|
||||
register-host.bat prompts for ID, calls install-host.ps1
|
||||
com.rcjav.host.json generated by install-host.ps1 (UTF-8 no BOM)
|
||||
logs/ host logs and delete audit log
|
||||
state/ scan progress state
|
||||
docs/
|
||||
INSTALL.md setup guide
|
||||
README.md this file
|
||||
EXTENSION_ID.md extension ID stability notes
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
- The host manifest's `allowed_origins` is pinned to your extension ID. Only that extension can connect.
|
||||
- No network ports opened.
|
||||
- Host only spawns `python rc-jav.py …`; no shell, no arbitrary code execution.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Quick reference — full troubleshooting in [`INSTALL.md`](./INSTALL.md#troubleshooting).
|
||||
|
||||
- Badge `?` → no JAV ID in title.
|
||||
- Badge `!` → host error. Read `host\logs\rcjav-host-stderr.log`.
|
||||
- "host unreachable" → re-run `install-host.ps1`, fully restart Brave.
|
||||
Reference in New Issue
Block a user