From 284b1ce8cd2fc865d1587f91db49ad5a8a632a77 Mon Sep 17 00:00:00 2001 From: zv Date: Mon, 1 Jun 2026 20:07:29 +0200 Subject: [PATCH] docs: add repository agent guide --- AGENTS.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d13fb80 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# AGENTS.md + +## Projekt + +`wtr.` to mobilna PWA pogodowa dla Polski. Pokazuje bieżące pomiary synoptyczne, dane hydrologiczne i ostrzeżenia z publicznego API IMGW oraz oddzielnie oznaczoną prognozę modelową Open-Meteo. Open-Meteo Geocoding służy także do wyszukiwania miejscowości. + +Stack: Next.js App Router, React, TypeScript, Tailwind CSS, TanStack Query, Zustand, Framer Motion, Recharts i Lucide React. PWA korzysta z manifestu oraz własnego service workera. + +Najważniejsze katalogi: + +- `app/` - routing, layout, globalne style i route handlery proxy. +- `components/` - komponenty pogody, prognozy, hydro, ostrzeżeń, layoutu, UI i stanów ekranu. +- `hooks/` - hooki TanStack Query. +- `lib/` - fetchery, normalizacja danych, tłumaczenia, helpery i store Zustand. +- `types/` - typy danych IMGW, prognozy oraz lokalizacji. +- `public/` - manifest, service worker i ikony PWA. + +## Komendy + +Wymagany jest Node.js 20.9 lub nowszy. + +```bash +npm install +npm run dev +npm run lint +npm run build +npm run start +``` + +Repozytorium nie ma obecnie skryptu testów, osobnego skryptu type-check ani formattera. `npm run build` uruchamia kontrolę TypeScript wykonywaną przez Next.js. Nie opisuj ani nie uruchamiaj nieistniejących komend jako standardowego workflow. + +## Konwencje kodu + +- Używaj TypeScript konsekwentnie i importów absolutnych `@/...`. +- Komponenty i typy nazywaj `PascalCase`, funkcje oraz hooki `camelCase`; hooki zaczynają się od `use`. +- Trzymaj routing w `app/`, komponenty funkcjonalne w odpowiednim podkatalogu `components/`, zapytania Query w `hooks/`, fetchery i normalizację w `lib/`, a typy danych w `types/`. +- Dodawaj `"use client"` tylko tam, gdzie komponent lub moduł korzysta z hooków, stanu przeglądarki albo interakcji. +- Dane zewnętrzne pobieraj przez route handlery Next.js. Nie omijaj allowlisty w `app/api/imgw/[...path]/route.ts`. +- Traktuj IMGW jako źródło bieżących pomiarów, hydro i ostrzeżeń. Prognozę Open-Meteo pokazuj oddzielnie jako prognozę modelową. Nie generuj fikcyjnych danych ani nie przedstawiaj prognozy jako pomiaru IMGW. +- Normalizuj zewnętrzne odpowiedzi i obsługuj `null`, puste pola oraz błędne wartości. Brak danych pokazuj jawnie zamiast uzupełniać estymacją. +- Dla pobierania danych używaj TanStack Query z sensownym `queryKey`, cache i retry. W UI zachowuj loading, error, retry oraz empty states. +- Teksty interfejsu dodawaj równolegle po polsku i angielsku w `lib/i18n.tsx`. Nazw stacji i treści IMGW nie tłumacz automatycznie. +- Trwałe preferencje użytkownika zapisuj przez istniejący store Zustand w `lib/store.ts` lub istniejące klucze `localStorage`. +- Zachowuj mobile-first UI, dostępność klawiatury, `aria-label`, focus states oraz spokojny styl glassmorphism. +- Nie edytuj ręcznie `next-env.d.ts`; plik jest generowany przez Next.js. + +Obsługa błędów: + +- Route handlery zwracają kontrolowane odpowiedzi JSON z kodem HTTP. +- Fetchery w `lib/` rzucają `Error`, a komponenty prezentują czytelny stan błędu i retry. +- Projekt nie ma warstwy logowania aplikacyjnego. Nie dodawaj przypadkowych `console.log`. + +## Instrukcje dla agenta + +- Przed zmianą przeczytaj pliki w obszarze funkcji i sprawdź `git status`. +- Utrzymuj mały zakres zmian. Nie refaktoruj niezwiązanych modułów i nie cofaj cudzych zmian. +- Nie dodawaj mocków jako źródła danych pogodowych. Przy zmianie źródeł API zaktualizuj route handler, typy, normalizację, UI i README. +- Przy zmianach PWA sprawdź spójność `public/manifest.json`, `public/sw.js` i rejestracji service workera. +- Przed zakończeniem uruchom co najmniej `npm run lint` i `npm run build`. Jeśli dodano testy, uruchom także ich skrypt. +- Sprawdź `git diff --check` oraz `git status`. Nie commituj wygenerowanego churnu w `next-env.d.ts`. +- Ważne decyzje o źródłach danych, ograniczeniach API, uruchamianiu i wdrożeniu dokumentuj krótko w `README.md`. + +## Utrzymywanie pliku + +Aktualizuj `AGENTS.md` w tej samej zmianie, gdy zmieniają się: struktura projektu, komendy, konwencje, zależności, sposób uruchamiania, testowania lub istotne decyzje architektoniczne. + +Jeśli ten plik jest nieaktualny, niepełny albo sprzeczny z kodem, popraw go zamiast ślepo go przestrzegać. Zachowuj go krótkim i praktycznym: bez historii czatu, dziennika zmian i ogólnych porad niezwiązanych z repozytorium.