81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# AGENTS.md
|
|
|
|
This file provides guidance to WARP (warp.dev) when working with code in this repository.
|
|
|
|
## Project baseline
|
|
- Stack: Nuxt 4 + Vue 3 + TypeScript + Nuxt UI + Nuxt Content.
|
|
- Package manager: `pnpm` (see `packageManager` in `package.json`).
|
|
- The current `README.md` is mostly upstream template documentation; use scripts/config in this repo as source of truth.
|
|
|
|
## Commands used in this repo
|
|
- Install dependencies:
|
|
- `pnpm install`
|
|
- Start local dev server:
|
|
- `pnpm dev`
|
|
- Build production bundle:
|
|
- `pnpm build`
|
|
- Preview production build locally:
|
|
- `pnpm preview`
|
|
- Lint:
|
|
- `pnpm lint`
|
|
- Typecheck:
|
|
- `pnpm typecheck`
|
|
|
|
### Database/Drizzle commands
|
|
- Push schema:
|
|
- `pnpm db:push`
|
|
- Generate migrations:
|
|
- `pnpm db:generate`
|
|
- Open Drizzle Studio:
|
|
- `pnpm db:studio`
|
|
|
|
Note: `drizzle.config.ts` points to `server/db/schema.ts`, but the repository currently has `server/db/schema.ts.bak` (not `schema.ts`). DB commands may fail until schema paths/files are aligned.
|
|
|
|
## Testing status
|
|
- There is no automated test script in `package.json` and no test runner config (`vitest`, `jest`, `playwright`, etc.) checked in.
|
|
- “Run a single test” is currently not applicable in this repository.
|
|
- For validation, use:
|
|
- `pnpm lint`
|
|
- `pnpm typecheck`
|
|
- manual verification via `pnpm dev`
|
|
|
|
## High-level architecture
|
|
### 1) Data model and content source
|
|
- Primary app data comes from markdown/content files in `content/novels/**` via Nuxt Content (`queryCollection('content')`).
|
|
- Pattern:
|
|
- One novel metadata file per novel (`content/novels/<slug>/index.md`)
|
|
- Chapter files per novel (`content/novels/<slug>/ch-*.md`)
|
|
- Homepage curation file at `content/novels/homepage.md` (featured/trending/recent lists).
|
|
|
|
### 2) Frontend structure and routing
|
|
- UI shell and navigation live in `app/layouts/default.vue` (dashboard/sidebar/search structure).
|
|
- Page routes are file-based under `app/pages/**`.
|
|
- Core user-facing routes:
|
|
- `/` homepage (`app/pages/index.vue`)
|
|
- `/novels/[id]` novel detail + chapter list (`app/pages/novels/[id].vue`)
|
|
- `/novel/[novelId]/[chapterId]` chapter reader (`app/pages/novel/[novelId]/[chapterId].vue`)
|
|
- `/titles/search` advanced catalog search (`app/pages/titles/search.vue`)
|
|
- `/myreading/*` local user state views (history/library/updates).
|
|
|
|
### 3) Chapter identity and reader navigation
|
|
- Chapter URLs are intentionally not the raw `ch-<n>` IDs.
|
|
- Both `app/pages/novels/[id].vue` and `app/pages/novel/[novelId]/[chapterId].vue` generate deterministic UUIDv5 chapter IDs using the same namespace constant and `${novelId}/${internalId}` seed.
|
|
- This UUID mapping is critical for route compatibility and resume/history behavior.
|
|
|
|
### 4) State and persistence strategy
|
|
- Persistent user-specific state is currently browser-side via `localStorage`:
|
|
- `user_library`
|
|
- `reading_history`
|
|
- `readerPreferences`
|
|
- Shared logic lives in `app/composables/useReaderStorage.ts`.
|
|
- `myreading` pages and reader screens consume this composable and/or the same storage keys directly.
|
|
|
|
### 5) Server API layer
|
|
- Nitro handlers under `server/api/**` expose novels/chapters/search endpoints.
|
|
- Current handlers also read from Nuxt Content (`queryCollection('content')`), not from a live DB.
|
|
- `server/data/*.json` exists as legacy/sample data and is not the primary source for the current UI flows.
|
|
|
|
### 6) Repository caveats to know before editing
|
|
- `app/pages/oldbak/**` contains older backup pages; avoid treating this directory as active product surface unless explicitly migrating/reviving it.
|
|
- Type interfaces in `app/types/index.d.ts` include both dashboard-template sample types and web-novel-specific types; be careful to update the right domain types.
|