yiekheng
64babc0d91
Replaces the earlier subtree docs with submodule clone/pull/push flow and notes where local-only files live. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
85 lines
4.5 KiB
Markdown
85 lines
4.5 KiB
Markdown
# 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 submodules** — the umbrella pins a commit SHA per sub-project, and `cd`-ing into a sub-dir gives you that sub-repo's own `.git`, history, and branch.
|
|
|
|
| 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`).
|
|
|
|
## Submodule workflow
|
|
|
|
First clone — must recurse, otherwise the sub-dirs come up empty:
|
|
|
|
```bash
|
|
git clone --recurse-submodules https://gitea.04080616.xyz/yiekheng/sunnymh.git
|
|
# or, after a plain clone:
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Day-to-day inside a sub-project:
|
|
|
|
```bash
|
|
cd manga-dl
|
|
# sub-dir has its own .git file pointing to ../.git/modules/manga-dl/
|
|
# `git log`, `git status`, `git commit`, `git push` all talk to the sub-repo's remote (sunnymh-manga-dl.git)
|
|
git pull origin main
|
|
# edit, commit, push — this goes to the sub-repo's remote, NOT the umbrella
|
|
```
|
|
|
|
After a sub-repo is updated, bump the pinned SHA in the umbrella:
|
|
|
|
```bash
|
|
cd .. # back to umbrella root
|
|
git add manga-dl # stages the new submodule SHA
|
|
git commit -m "Bump manga-dl to <short-sha>"
|
|
git push
|
|
```
|
|
|
|
Pull upstream updates that bumped submodule SHAs:
|
|
|
|
```bash
|
|
git pull
|
|
git submodule update --recursive # check out the SHAs the umbrella now points at
|
|
```
|
|
|
|
Local-only files inside each submodule (gitignored at the sub-repo level, never pushed anywhere): `.env`, `manga-dl/.browser-data/`, `manga-dl/cookies.txt`, `manga-site/node_modules/`, `manga-site/.next/`, `manga-site/tsconfig.tsbuildinfo`, `manga-site/.claude/`, `manga-site/.agents/`, `manga-site/reference/`.
|
|
|
|
The umbrella also has a root-level `.env` — shared R2 + DB credentials, single source of truth. It's untracked (not in a remote). Sub-projects currently still read their own `.env` copies; see the migration note in `MEMORY.md` / conversation history.
|
|
|
|
## 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.
|