Lucas WintherandClaude Opus 5.5
dd2d5a94bc
The user signed off the spec. The server runs self-hosted under Bun; the password gate and the Cloudflare Workers entry stay designed but deferred until abuse or traffic calls for them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
94 lines
6.8 KiB
Markdown
94 lines
6.8 KiB
Markdown
# 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 — 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.
|