mangabaka-seeder/AGENTS.md

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

Verified 2026-10-14 (see docs/PERMISSIONS.md): bun install --frozen-lockfile · bun test · bun test test/<file>.test.ts · bun run typecheck · bun run build (page + userscript into dist/web/) · bun run start (server; env vars in docs/ARCHITECTURE.md). 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:

// 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 or other credentials. Never force-push, rewrite pushed history, or commit directly to main.

Ask first: new runtime dependencies · deploying, or any server 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.