mangabaka-seeder/docs/DECISIONS.md

Decisions

Append-only. Never edit or delete an entry — supersede it with a new one that links back. One entry per decision a future maintainer would otherwise have to reverse-engineer. No index: grep -n '^## ' docs/DECISIONS.md lists every entry (date, title, line number).

2026-10-14 — Adopt AGENTS.md as single source of truth

Status: accepted Context: Agents had no durable project context and no consistent workflow between sessions. The design context lived in HANDOVER.md, which is now split into this file, the spec and docs/TODO.md. Decision: AGENTS.md is canonical; CLAUDE.md/GEMINI.md are pointers. Specs are permanent in docs/specs/. Plans live in docs/plans/ only while work is in progress and are removed before the merge request. Both override the superpowers default paths. Alternatives: Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore the repo every session — measurably slower and more tokens). Consequences: Rule changes happen in one file; pointer files must stay thin. Plans are working artefacts: kept after merge they go stale and contradict the code, so the spec is the record.

2026-10-14 — Implementation details: server API, Webtoons fetch forms

Status: accepted Context: Decisions made while implementing plan 001 that the spec leaves open. Decision:

• createApp(env) returns the handler (spec §4.10 says handle(req, env)) so rate-limit state is bound once.
• /api/* accepts Origin: https://mangabaka.org besides our own, for the userscript.
• Behind the proxy, the rate limiter keys on the last X-Forwarded-For entry; earlier ones come from the client.
• /api/fetch buffers responses up to 20 MB instead of streaming: a simple cap; pages and covers are far smaller.
• Webtoons is fetched as /-/-/-/list?title_no=N (official) or /-/canvas/-/list?title_no=N (canvas); the wrong form is a 404, so the other is tried. A made-up slug made Webtoons hang, so the user's own path is never fetched.
• Test fixtures are marked -text in .gitattributes to stay byte-exact. Alternatives: Stream /api/fetch (needs a counting stream for the cap); trust the first X-Forwarded-For entry (spoofable). Consequences: Reverse proxies must append to X-Forwarded-For (see docs/ARCHITECTURE.md).

2026-10-14 — Spec amendments from testing the real services

Status: accepted (amends spec 001 §2.2–§4.5) Context: Before planning, we parsed real pages and downloaded every cover for Tower of God (current + Wayback every 6 months, 2015–2026) and the canvas example; the user reviewed them in samples/ (gitignored). Findings: Wayback answered 429 "suspected abusive bot traffic" to a fake Chrome User-Agent but nothing at all to an honest one at one request per 10 s; most historical og:images are character or landing-page art, not covers; MangaBaka requires exactly one is_default per series; the public images endpoint is paginated and lacks is_default. Decision:

• History granularity (every 1 / 3 / 6 / 12 months, default 6) over the span of captures, one snapshot per bucket — the user's idea, replacing "at most 60 snapshots".
• Wayback gets mangabaka-seeder/<version> (+repo URL) as User-Agent and one request per 10 s; a snapshot that fails after retries stops the history and keeps partial results.
• Images taller than 1.6 : 1 are "landing-page art": type other, not selected by default.
• "Make this the series' main cover" is a checkbox, on by default, warning that it replaces the main cover for every language.
• Retries only for GET/HEAD, never POST. Alternatives: A fixed snapshot limit (arbitrary; either misses years or wastes requests); spoofing a browser more convincingly (dishonest, and the honest UA simply works); dropping tall art entirely (it is genuine Webtoons art some editors may want). Consequences: A default run costs ~4–5 minutes of Wayback time, so the UI needs progress and cancel. Our server makes every user's Wayback requests from one IP — if that gets blocked, the userscript (user's own IP) still works.

2026-10-14 — Size cap on the covers folder; refuse when full, never evict

Status: accepted (extends "Server storage is a plain folder" below) Context: The user asked for storage limits on the local folder. The site is open (no gate), so uploads must not be able to fill the server's disk. Decision: MBSEED_STORAGE_MAX_BYTES (default 1 GiB) caps the folder. Uploads past it get 507 and the page offers litterbox/catbox instead. Files are never deleted before their 30 days. Alternatives: Evict the oldest files (rejected: their links may be in requests still awaiting review, which would break them silently); per-IP upload quotas (deferred until abuse shows up). Consequences: Under heavy use the server host becomes unavailable until the sweep frees space.

2026-10-14 — Server storage is a plain folder on our server

Status: accepted (replaces the S3/R2 storage in the entries below) Context: Self-hosted, a bucket is extra infrastructure. The user chose: "For now, store images in a plain folder on the server." Decision: MBSEED_STORAGE_DIR holds <sha256>.<ext>; our server serves it at /covers/… under MBSEED_PUBLIC_URL. bun.ts deletes files older than 30 days (by mtime) at startup and every 24 hours. Writes are temp file + rename. It sits behind the Storage interface. Alternatives: S3-compatible bucket (MinIO, R2, B2) with a lifecycle rule — kept as a later option. Consequences: The server must be publicly reachable for MangaBaka to fetch covers, and its uptime now matters until each review is done. Folder access needs Bun APIs, so it lives in storage-dir.ts, not in the web-standard app.ts.

2026-10-14 — Spec signed off; self-hosted only; password gate deferred

Status: accepted (narrows the entry below) Context: The user signed off spec 001 and said the app will run self-hosted, and that password-gating should wait: "if it gets abused or we see too big amounts of traffic, we will deal with it then." Decision: First version runs server/app.ts under Bun.serve on our own machine behind our reverse proxy. No gate, no Cloudflare entry; both stay designed in the spec (§4.10, §4.11) and are listed under Someday in docs/TODO.md. The handler stays web-standard so either can be added later. Alternatives: Build the gate now (cost without a demonstrated need). Consequences: The site is open: the host allowlist, the 20 MB cap and the per-IP rate limit are the only protections. The rate limit needs the real client IP from our reverse proxy (MBSEED_TRUST_PROXY).

2026-10-14 — Also support catbox/litterbox; optional password gate; self-hostable server

Status: accepted (extends the two entries below) Context: The user asked for catbox/litterbox support as well, and for a way to password-gate the static site "such that we could lock the service behind our own server". Decision: Image hosts are server (our storage, 30 days, default when configured), litterbox (≤ 72h; uploaded straight from the browser, which works because litterbox sends CORS headers), catbox (permanent; through our server for the page, direct for the userscript) and direct. The server is one web-standard fetch handler with two thin entries: Cloudflare Workers (R2 binding) and Bun.serve (S3-compatible bucket) for our own machine. An optional shared password (MBSEED_PASSWORD) gates every route, static assets included, with an HMAC-signed session cookie, plus Authorization: Bearer for the userscript. Self-hosted instances may use the reverse proxy's auth instead. "Behind our own server" was read as covering both the built-in gate and self-hosting. Alternatives: Cloudflare Access in front of the Worker (free for small teams, but Cloudflare-only and no help when self-hosting); per-user accounts (not needed for a small group); Basic auth (can't log out, and the browser prompt is clumsy for the userscript). Consequences: On Workers, assets must run through the Worker (run_worker_first) or the gate leaks the page. The userscript works without any server when using litterbox or catbox. Litterbox links may die before a slow review; the UI warns about it.

2026-10-14 — Temporary image hosting: Cloudflare R2 with a 30-day expiry

Status: accepted (supersedes "Rehosting on catbox.moe" below) Context: A static page can't upload to catbox.moe (no CORS). The user said temporary hosting is fine with an expiry of at most a month: if moderators take longer, the user reruns. Decision: The Worker rehosts into R2 at covers/<sha256>.<ext>, with a bucket lifecycle rule deleting objects after 30 days. direct (no rehost) stays as an option. Alternatives: litterbox (CORS works, but 72h maximum — likely shorter than a review); 0x0.st (CORS and MangaBaka acceptance unverified); catbox (no CORS, permanent). Consequences: Needs a Cloudflare account with a card on file (R2). Expected cost is $0 on free tiers; abuse of the Worker is the cost risk, hence the allowlist and the per-IP rate limit.

2026-10-14 — Static page + Cloudflare Worker, and a userscript; Bun; links given directly

Status: accepted (supersedes "Stack: TypeScript / Node CLI" and "Automatic series matching" below) Context: The user wants a static web page first, with the CLI as secondary, Bun instead of Node, and to pass both the MangaBaka and Webtoons links. Checked 2026-10-14: api.mangabaka.org sends access-control-allow-origin: * (submissions too); Webtoons HTML, pstatic images and Wayback do not. Decision: One pure core with an injected Transport. The page uses a Worker proxy (allowlisted hosts) for Webtoons/Wayback and calls MangaBaka directly. The userscript uses GM_xmlhttpRequest and needs no proxy for fetching. The user chose to pursue both front ends. Tooling is Bun (bun test, bun build). No automatic MangaBaka search; a title_no link check only warns. Alternatives: Local Bun server only (not a hosted page); userscript only. Consequences: Two front ends to keep in step; the Worker is public infrastructure to protect. Cloudflare IPs may be throttled by Webtoons/Wayback — the userscript doesn't have that risk.

2026-10-14 — Original design decisions (from the design conversation)

Status: partly superseded — see the two entries above Context: Recorded in the former HANDOVER.md. Decision:

• Stack: TypeScript, chosen over Go (yambs is Go) to keep a browser extension or userscript possible. Runtime superseded: Bun, not Node.
• Submission path: the API when a token is available, otherwise help with manual entry.
• Which images: all — poster, square thumbnail, banner/background and foreground art.
• Historical covers through the Wayback Machine.
• Main cover: the current poster (square for canvas) gets is_default: true, existing covers false.
• Rehosting on catbox.moe by default. Superseded: R2, 30 days.
• Content rating chosen by the user, default safe; mature titles show a warning.
• Image bytes kept in memory; sizes up to ~650 KB seen; 20 MB cap.
• Extensibility: new sources and image hosts are one module plus one registry line.
• Safety: nothing uploaded or sent without explicit user action; save_mode: "review".
• Not now: fields other than images; following language editions.
• Automatic series matching via /v2/series/match. Superseded: links given directly. Alternatives: not recorded Consequences: See the spec.