sulthan/mangaBookmark
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: propagate novel library + new sites into stale AGENTS.md top-matter

Browse Source 
The rebrand (4229c17) rewrote root AGENTS.md as a compression pass and
switched Bromite->Violentmonkey, but the description still called the
project a manga-only tracker over two sites. Six sites, two libraries and
two userscripts now exist.

Root AGENTS.md:
- 'What this is' names both scripts and their sites, the kind column, and
  the <site>:<series_id> key shape.
- Origins constraint generalised past Asura/Demonic.
- Records that kagane and novelfull are reliably Cloudflare-challenged and
  browser-polled, which is the standing exception to the 'blocking is
  IP-reputation-based and not reproducible' note directly above it.
- Diagram says two userscripts.

backend/AGENTS.md:
- Store key list gained novelfull|lightnovelworld and the kind column.
- NOVEL_USERSCRIPT_PATH documented; it shipped in main.go:150 undocumented.

Child userscript/AGENTS.md already covered the novel adapters, so it is
untouched.
This commit is contained in:
Sulthan Zaki
2026-08-06 18:16:05 +07:00
parent 91565252d5
commit 5d4d890c34
2 changed files with 14 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+9 -3
View File
@@ -4,21 +4,27 @@ Guidance for OpenCode (and Claude Code) working in this repo.
## What this is
Manga read-progress tracker, user read on **asurascans.com** (current domain; asuracomic.net 301s here) and **demonicscans.org** via **Violentmonkey**. Userscript inject on-page UI (floating button + slide-in panel), sync progress to self-hosted Go backend so bookmarks unify across both sites and devices.
Read-progress tracker for two libraries — manga and novels — behind one self-hosted Go backend. Two separate Violentmonkey userscripts inject on-page UI (floating button + slide-in panel) and sync progress, so bookmarks unify across sites and devices:
- `manga-bookmark.user.js` — **asurascans.com** (current domain; asuracomic.net 301s here), **demonicscans.org**, **comix.to**, **kagane.to**.
- `novel-bookmark.user.js` — **novelfull.com**, **lightnovelworld.net**.
One backend, one `bookmarks` table: a `kind` column (`manga`|`novel`) splits the libraries and the web UI switches between them. Rows are keyed `<site>:<series_id>`.
## Hard constraints (drive design — don't violate)
Userscript targets **Violentmonkey**, so `GM_*` APIs available, but stay GM-free where plain web APIs suffice — keeps portability across engines:
- **Avoid `GM_*` unless needed.** Prefer page `localStorage` over `GM_setValue`/`GM_getValue`, on-page UI over `GM_registerMenuCommand`, plain `fetch()` over `GM_xmlhttpRequest` for cross-origin.
- Cross-origin `fetch()` work **only** against CORS-enabled backend. Manga sites `https://`, so backend **must be HTTPS** (else mixed-content block).
- Asura and Demonic are **separate origins with separate `localStorage`** — shared remote store only way to unify bookmarks. Cloud sync required, not optional.
- Every site is its **own origin with its own `localStorage`** — a shared remote store is the only way to unify bookmarks. Cloud sync required, not optional.
- Userscript run in **isolated world**, so embedded API token safe from site's JS.
- Cloudflare's block on manga sites **IP-reputation-based, not universal — and not reliably reproducible.** Verified 2026-07-26: plain `curl` from both CGNAT dev machine *and* deployed VPS got clean 200s with real HTML on both asurascans.com and demonicscans.org (homepage, series, chapter pages) — no interactive Turnstile challenge from either IP at test time. Contradicts earlier untested assumption CGNAT dev IP blocked; wasn't, at least this date. Treat "does curl work right now" as live, time-varying fact to re-check, not fixed property of machine — Cloudflare's bot scoring can flip previously-clean IP without notice. Backend fetcher still needs graceful-degrade path for when challenged, and adapters should be **verified against live pages** (Playwright MCP, on-device devtools, direct probe) before finalizing, not assumed from single earlier test.
- **kagane.to and novelfull.com are the exception to the above** — both sit behind a Cloudflare JavaScript challenge no TLS fingerprint clears, so the backend polls them over CDP (`BROWSER_WS_URL`) and skips them entirely when that's unset. The four other sites poll fine over plain TLS.
## Architecture
```
Violentmonkey userscript (isolated world, per-site adapters, localStorage cache)
Two Violentmonkey userscripts (isolated world, per-site adapters, localStorage cache)
-- fetch() HTTPS --> reverse proxy (TLS + CORS) --> Go net/http --> SQLite (volume)
```