Lucas WintherandClaude Opus 5.5
219a05c039
Revise the covers spec: both links given directly, static page served by a Cloudflare Worker plus a userscript on one pure core, Bun instead of Node, and R2 rehosting with a 30-day expiry. Move the spec to docs/specs/, merge HANDOVER.md into docs/DECISIONS.md, the spec and docs/TODO.md, and add AGENTS.md, pointer files, PERMISSIONS.md and agent permission configs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
62 lines
4.4 KiB
Markdown
62 lines
4.4 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 — 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.
|