Initial snapshot before step 10 package split

2026-05-22 21:39:09 +02:00
commit e029e898e9
16 changed files with 3955 additions and 0 deletions
@@ -0,0 +1,59 @@
+# rc-jav (Python CLI)
+
+Session memory for Claude. Read before making changes here.
+
+## What this is
+
+A read-only rclone library comparison + search CLI. Compares `cq:JAV` remote (rclone crypt) against itself (dupe detection) or against external WinCatalog CSV/XML exports. Powers the rclone-jav Brave extension via native messaging.
+
+## Architecture
+
+```
+rc-jav.py
+  ├── reads config.json (default_target etc.)
+  ├── reads cache.json (per-remote file index, written by --scan)
+  ├── shells out to: rclone lsf / rclone lsjson / rclone size --json
+  ├── extract_id() per filename → normalized ID with optional #partN / variant suffix
+  ├── two query modes: --quick (live rclone --include glob) and cached (uses cache.json)
+  └── output: rich tables (default) | --basic plain | --format json (for extension)
+```
+
+## Files
+
+```
+D:\DEV\Project\rclone-jav\
+├── rc-jav.py             single-file CLI
+├── config.json           default_source/target/catalog (user-editable via --save)
+├── cache.json            scanned remote file index (written by --scan)
+├── wincatalog\           drop WinCatalog CSV/XML exports here (auto-loaded)
+├── TODO.md               deferred work
+└── README.md
+```
+
+## Companion project
+
+`D:\DEV\Extensions\Production\rclone-jav\` (PC 1) / `D:\DEV\Extensions\Staging\rclone-jav\` (PC 2) — Brave extension + native messaging host that shells out to `rc-jav.py` for searches.
+
+## ID normalization
+
+- `extract_id()` chops trailing single letters (e.g. `IBW-902z.mp4` → `IBW-902`). Decision is intentional — see extension's CLAUDE.md "Decision log".
+- Part suffix detection: `_1`, `-pt1`, `(1)` → appended as `#partN` for distinctness.
+- Compound prefixes (`FC2-PPV-123`) handled via secondary regex.
+- Search matcher does prefix lookup so `IBW-902` finds both `IBW-902` and `IBW-902#part1` etc.
+
+## Defaults from earlier sessions
+
+- `cq:JAV` is the current remote root (after the rclone crypt config change moved it down a level)
+- `default_target` in config.json = `["cq:JAV"]`
+- `human_size()` formats to 2 decimals (e.g. `6.94 GiB`)
+
+## TODO
+
+See `TODO.md`. Current item: WinCatalog `\` → `/` path normalization in load_catalog_*.
+
+## When making changes
+
+- Adding CLI flags: also update host invocation in `D:\DEV\Extensions\Production\rclone-jav\host\rcjav-host.py` if the flag matters to the extension
+- Changing `extract_id()` semantics: forces a `--scan` to rebuild cache under new keys, and may need a parallel change in extension's `normalizeId()`
+- JSON output format changes: extension's popup.js / overlay rendering reads `structured` array — keep field names stable (`source`, `remote`, `path`, `full_path`, `size`, `size_human`, `mod_time`, `jav_id`)
+- Config schema: update `--save` writer and any defaults