79 lines
2.4 KiB
Markdown
79 lines
2.4 KiB
Markdown
# AI Agent Instructions
|
|
|
|
This file is the first-stop context for AI coding agents working in this repo.
|
|
|
|
## Repository identity
|
|
|
|
- Project: Arkie Library Frontend / ARK database web UI.
|
|
- Package name: `ark-database-web`.
|
|
- Stack: React 18, TypeScript, Vite, Tailwind CSS, React Router, RainbowKit/Wagmi.
|
|
- Backend API is expected at `/api`; uploaded assets under `/uploads`.
|
|
|
|
## Branch rules
|
|
|
|
- Current deploy branch: `main`.
|
|
- Work/staging branch available: `terry-staging`.
|
|
- Do not commit or push unless Terry explicitly asks.
|
|
- Pushing to `main` triggers production frontend deploy via Gitea Actions.
|
|
- Before branch-changing or pulling, run `git status --short --branch` and preserve local work.
|
|
|
|
## Required checks
|
|
|
|
Before proposing a push or deploy, run:
|
|
|
|
```bash
|
|
npx tsc --noEmit
|
|
npm run format:check
|
|
npm test
|
|
```
|
|
|
|
If code formatting is needed, run:
|
|
|
|
```bash
|
|
npm run format
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `tsconfig.json` has `strict`, `noUnusedLocals`, and `noUnusedParameters`; unused imports fail CI.
|
|
- `dist/` is build output and should not be edited manually.
|
|
|
|
## App structure quick map
|
|
|
|
- `src/main.tsx` chooses normal app vs admin-only build using `VITE_ADMIN_ONLY`.
|
|
- `src/App.tsx` contains public routes and conditionally exposes admin routes unless `VITE_DISABLE_ADMIN === "true"`.
|
|
- `src/api.ts` defines `apiBase`, fetch helpers, and shared resource/category types.
|
|
- `src/i18n.tsx` contains all UI copy for `zh-TW`, `zh-CN`, and `en`.
|
|
- `src/pages/admin/` contains admin UI screens.
|
|
- `src/adminPaths.ts` handles admin path prefix logic. Keep it in sync with backend/nginx admin host config if changed.
|
|
|
|
## Environment variables
|
|
|
|
See `.env.example` and `README.md` for details. Do not commit real secrets or private deployment keys.
|
|
|
|
Common production public build env:
|
|
|
|
```bash
|
|
VITE_API_URL=https://api.ark-library.com
|
|
VITE_DISABLE_ADMIN=true
|
|
```
|
|
|
|
## Deployment context
|
|
|
|
`.gitea/workflows/deploy.yml` deploys on push to `main`:
|
|
|
|
1. `npm ci`
|
|
2. `npx tsc --noEmit`
|
|
3. `npm run format:check`
|
|
4. `npm test`
|
|
5. `npm run build` with production public env
|
|
6. rsync `dist/` to both frontend servers
|
|
7. compare remote `index.html` checksums
|
|
|
|
## Agent behavior preferences
|
|
|
|
- Answer Terry in concise Chinese unless the task requires code/docs in English.
|
|
- Prefer small, direct fixes over broad refactors.
|
|
- Update README/docs/memory when learning non-obvious project facts.
|
|
- Search existing project memory before making decisions about workflow, deploy, or conventions.
|