From 7a48ee1a2bd1ffb8146e96c0ed25553694352bdd Mon Sep 17 00:00:00 2001
From: yiekheng <yiekheng@04080616.xyz>
Date: Sun, 12 Apr 2026 18:33:50 +0800
Subject: [PATCH] Initialize sunnymh umbrella repo

Add root CLAUDE.md documenting the multi-project layout, subtree workflow,
and cross-project invariants shared between manga-dl (scraper) and
manga-site (Next.js reader).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .gitignore |  1 +
 CLAUDE.md  | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 CLAUDE.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e43b0f9
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..425cdbb
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository layout
+
+`sunnymh` is the umbrella repo for the 晴天漫画 · Sunny MH product. Each sub-project is its own git repo with its own remote on Gitea (`gitea.04080616.xyz/yiekheng/sunnymh-*`). The umbrella ties them together via **git subtree** so a single clone contains the whole system, while the sub-repos remain independently pushable.
+
+| Path | Role | Remote | Detailed guide |
+|---|---|---|---|
+| `manga-dl/` | Python TUI scraper — downloads manga from m.happymh.com, writes WebP to Cloudflare R2 + rows to Postgres | `sunnymh-manga-dl.git` | `manga-dl/CLAUDE.md` |
+| `manga-site/` | Next.js 16 App Router reader — signed R2 URLs, placeholder-based reader, iOS Safari tuned | `sunnymh-manga-site.git` | `manga-site/CLAUDE.md` |
+
+More sub-projects may be added over time. Always read the sub-project's own `CLAUDE.md` before touching its code — the two stacks have very different invariants (Playwright/CDP anti-bot in `manga-dl`; placeholder-shift invariants in `manga-site/PageReader.tsx`).
+
+## Subtree workflow
+
+The sub-dirs currently still hold their own `.git` (independent clones). To convert a sub-dir into a tracked subtree of this umbrella:
+
+```bash
+# one-time, per sub-project — run from sunnymh root
+git remote add manga-dl-origin   https://gitea.04080616.xyz/yiekheng/sunnymh-manga-dl.git
+git remote add manga-site-origin https://gitea.04080616.xyz/yiekheng/sunnymh-manga-site.git
+
+# archive the existing working copy, then subtree-add from the remote
+mv manga-dl manga-dl.bak && rm -rf manga-dl.bak/.git   # keep local-only files like .env, .browser-data
+git subtree add --prefix=manga-dl manga-dl-origin main --squash
+# then copy .env / .browser-data / cookies.txt / debug/ back into manga-dl/
+```
+
+Day-to-day:
+
+```bash
+# pull upstream changes for one sub-project
+git subtree pull --prefix=manga-dl manga-dl-origin main --squash
+
+# push umbrella-side edits back to the sub-repo's remote
+git subtree push --prefix=manga-dl manga-dl-origin main
+```
+
+Local-only files that must NOT be pushed to the sub-repo remote (already in each sub-repo's own `.gitignore`): `.env`, `manga-dl/.browser-data/`, `manga-dl/cookies.txt`, `manga-site/node_modules/`, `manga-site/.next/`, `manga-site/tsconfig.tsbuildinfo`.
+
+## Cross-project invariants
+
+These two sub-projects share infrastructure — changes on one side often require a matching change on the other.
+
+- **Shared Postgres schema**: `Manga`, `Chapter`, `Page` (camelCase identifiers, Prisma-style). `manga-dl/manga.py` writes raw SQL via `psycopg2`; `manga-site/prisma/schema.prisma` reads via Prisma. **When the Prisma schema changes, update every `INSERT INTO "Page"` / `"Chapter"` / `"Manga"` site in `manga.py` too.** Likewise when `manga.py` adds a column, update `schema.prisma` and run `npx prisma db push` + `npx prisma generate`.
+- **Shared R2 layout** (populated by scraper, consumed by site):
+  - `manga/<slug>/cover.webp`
+  - `manga/<slug>/chapters/<chapter_number>/<page_number>.webp`
+- **`Page.width` / `Page.height` are load-bearing**: the scraper writes them on insert; `manga-site/components/PageReader.tsx` uses them for aspect-ratio placeholders to avoid iOS Safari scroll-anchor bugs. Dims=0 causes layout shift on image load.
+- **Shared `.env` keys**: both sides read `DATABASE_URL`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY`, `R2_SECRET_KEY`, `R2_BUCKET`, `R2_PUBLIC_URL`. Each sub-repo has its own `.env` — keep the values in sync.
+
+## Common commands
+
+Run these from the respective sub-directory:
+
+```bash
+# manga-dl (python, no tests/lint)
+cd manga-dl && python manga.py
+
+# manga-site (Next.js 16)
+cd manga-site && npm run dev
+cd manga-site && npm run build
+cd manga-site && npm run lint
+cd manga-site && npx prisma db push   # this repo uses db push, NOT migrate dev
+```
+
+## Deployment
+
+Only `manga-site` is deployed (Proxmox VM → Docker → Portainer, behind aaPanel Nginx at `www.04080616.xyz` → `127.0.0.1:3001`). `manga-dl` is an operator-run local tool — it's not containerised and intentionally not headless (Cloudflare fingerprints real Chrome). See `manga-site/CLAUDE.md` for the full deploy flow.