lastwebnovel-app/AGENTS.md

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.