rclone-jav/AGENTS.md

rc-jav (Python CLI)

Session memory for Codex. 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 AGENTS.md "Decision log".
• JAV IDs are canonicalized with at least 3 digits (ABC-27 → ABC-027); 4+ digit IDs keep their width (ABCD-1294). User expects real JAV IDs to be ABC-027, never ABC-27 or ABC-0027.
• 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.
• Quick search must emit only canonical padded uppercase globs (ABC-027*, ABCDE-1167*). Do not add --ignore-case; user never uses lowercase filenames and it caused noticeable delay.

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"] (hardcoded fallback in cli.py matches)
• human_size() formats to 2 decimals (e.g. 6.94 GiB)
• After the 3-digit ID canonicalization change, run python rc-jav.py --scan to rebuild cache.json under the new padded keys.
• Duplicate KEEP ranking uses configurable VIP folders before source/size/format ranking. Default VIP folder is ClearJAV; video files there are treated as the trusted direct-rip copy.
• Duplicate KEEP ranking treats .ts as the lowest-priority video container when any non-.ts duplicate is available.

Recent decisions / bug fixes

• --format json should keep stdout as clean JSON. Status/progress text belongs on stderr in JSON mode.
• Catalog rows are informational. CSV exports mark them as CATALOG; JSON exports put them under catalog, not delete_candidates.
• Cache loading validates the top-level shape and falls back to an empty cache when remotes is missing or malformed.
• The old --recursive/-R flag was removed because scans are always recursive (rclone lsf -R / quick lsjson -R).

TODO

See TODO.md for deferred work.

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