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
4.9 KiB
Markdown
94 lines
4.9 KiB
Markdown
# mangabaka-seeder
|
|
|
|
Seeds cover edits into MangaBaka from a Webtoons series. TypeScript on **Bun** (not Node):
|
|
a pure core, a static page served by a small self-hosted Bun server, and a userscript.
|
|
No code yet — the approved design is `docs/specs/001-webtoons-covers.md`.
|
|
|
|
`AGENTS.md` is the single source of truth for agents here. `CLAUDE.md` and `GEMINI.md` only point here.
|
|
Deeper context on demand: `docs/ARCHITECTURE.md`, `docs/DECISIONS.md`, `docs/TODO.md`.
|
|
|
|
## Commands
|
|
|
|
TODO(maintainer): confirm commands once tooling exists. Planned (spec §6), none verified yet:
|
|
`bun install --frozen-lockfile`, `bun test`, `bun test test/<file>.test.ts`, `bunx tsc --noEmit`.
|
|
Use `bun`/`bunx` — never `npm`, `npx`, `node` or `vitest`.
|
|
|
|
## Workflow
|
|
|
|
Required skills: `superpowers`, `impeccable`. Check at session start; install if missing.
|
|
Specs → `docs/specs/NNN-slug.md` (permanent). Plans → `docs/plans/NNN-slug.md` while in progress;
|
|
`git rm` them before opening a merge request — the spec is the record.
|
|
(Overrides the superpowers default paths.)
|
|
|
|
Anything beyond a trivial fix: brainstorm → spec (sign-off) → plan (sign-off) → TDD → review.
|
|
TDD means failing test first, watch it fail, minimal code, watch it pass, commit.
|
|
Tick plan checkboxes as you go so an interrupted session is resumable.
|
|
Trivial changes (typo, version bump, one-line config): say "trivial, skipping spec" and proceed.
|
|
|
|
Use impeccable for the static page (`src/web/`) and the userscript panel — `craft` for new,
|
|
`audit`/`polish` on existing, `harden` before shipping. Design context: `PRODUCT.md`, `DESIGN.md`.
|
|
|
|
## Rules
|
|
|
|
- `src/core/` runs in a browser, a userscript and Bun: no DOM, no `Bun.*`, no `node:*`,
|
|
no `GM_*`. All network goes through the injected `Transport`; hashing uses `crypto.subtle`.
|
|
- `core/` never imports from `web/`, `server/`, `userscript/` or `cli/`. `server/app.ts` uses only
|
|
web-standard APIs (a Workers entry may come later); `bun.ts` stays a thin adapter.
|
|
- The MangaBaka token goes straight to `api.mangabaka.org` (CORS is open) — never through our server.
|
|
- MangaBaka `images` **replaces the whole set**: a save body must include every existing image.
|
|
Saves always use `save_mode: "review"`.
|
|
- Never call the MangaBaka save endpoint (`POST /v0/my/submissions/…` without `/preview`) yourself:
|
|
it files a real edit request. Tests use the fake transport; tests never touch the network.
|
|
- Fixtures in `test/fixtures/` are captured from real responses, never hand-written.
|
|
- `/api/fetch` only proxies allowlisted hosts; `/api/upload` takes a source URL, never raw bytes.
|
|
- The password gate (spec §4.11) and the Cloudflare entry are deferred: don't build them unasked.
|
|
- Webtoons image URLs: strip the `?type=` query and use the `swebtoon-phinf.pstatic.net` host:
|
|
|
|
```ts
|
|
// CORRECT https://swebtoon-phinf.pstatic.net/20250204_46/17386458444547o1b2_JPEG/95.jpg
|
|
// WRONG https://webtoon-phinf.pstatic.net/20250204_46/17386458444547o1b2_JPEG/95.jpg?type=crop540_540
|
|
// (403 without a Webtoons Referer, and a cropped variant)
|
|
```
|
|
|
|
## Architecture
|
|
|
|
src/core/ -> pure pipeline: sources, Wayback history, inspect, dedupe, seed, MangaBaka client
|
|
src/web/ -> static page · src/server/ -> assets, `/api/fetch`, `/api/upload` (`Bun.serve`)
|
|
src/core/hosting/ -> server storage (30 days), litterbox (≤72h), catbox (permanent), direct
|
|
src/userscript/ -> panel on mangabaka.org, `GM_xmlhttpRequest` · src/cli/ -> later
|
|
|
|
Full picture: `docs/ARCHITECTURE.md` and the spec — read them before your first change in a session.
|
|
|
|
## Boundaries
|
|
|
|
Never commit `.env*`, `.dev.vars`, tokens, passwords, S3 keys or Cloudflare credentials.
|
|
Never force-push, rewrite pushed history, or commit directly to `main`.
|
|
|
|
Ask first: new runtime dependencies · deploying, or any server/bucket configuration ·
|
|
real uploads to litterbox/catbox ·
|
|
anything sent to MangaBaka with a real token · anything destructive (`rm -rf`, `git reset --hard`) ·
|
|
work the approved plan does not cover.
|
|
|
|
If the task turns out much larger than the plan assumed: stop, report, re-plan.
|
|
|
|
## Docs duties
|
|
|
|
Same commit as the code, not "later":
|
|
- `docs/ARCHITECTURE.md` — when a module, boundary, or data flow changes.
|
|
- `docs/DECISIONS.md` — append-only; any choice a future maintainer would reverse-engineer.
|
|
- `docs/TODO.md` — anything noticed and deliberately not fixed. No `TODO` comments in source.
|
|
- `docs/PERMISSIONS.md` — together with `.claude/settings.json`, `.codex/` and
|
|
`.gemini/settings.json`, in one commit.
|
|
|
|
## Git
|
|
|
|
Branches: `feat|fix|chore/<slug>`. Commits: Conventional Commits (`docs: …`, `feat: …`).
|
|
Small, each leaving tests green.
|
|
|
|
## Done means verified
|
|
|
|
Do not report success on work you have not run. Before saying done:
|
|
tests run *in this session* and seen passing · typecheck clean · matches the approved spec ·
|
|
docs duties complete · `git status` clean and the diff is only what you intended.
|
|
"It should work" is not verification.
|