chore: migrate from Linear to Plane MCP, add .agent/ framework
- Add .agent/ directory with AGENTS.md, steering docs, workflows, references - Replace CLAUDE.md with slim reference pointing to .agent/ - Migrate TODO.md from Linear ZEE-* to Plane MITHOME-* identifiers (26 issues synced) - Add .mcp.json.example with Plane MCP server config - Remove .agents/, .cursor/, .roo/ legacy directories - Update .gitignore: add .mcp.json, remove old IDE dirs - Replace linear-sync.js approach with Plane MCP server (@makeplane/plane-mcp-server)
This commit is contained in:
Do Siki
@@ -0,0 +1,362 @@
|
||||
# AGENTS.md — AI Agent Szabályok és Irányelvek
|
||||
|
||||
> **[CRITICAL SYSTEM DIRECTIVE FOR AI]**
|
||||
> Mielőtt BÁRMILYEN feladatba belekezdesz, KÖTELEZŐ elolvasnod a `.agent/steering/` mappa összes fájlját!
|
||||
> Ezek elolvasása nélkül ne írj és ne módosíts kódot!
|
||||
|
||||
> Ez a fájl az elsődleges referencia minden AI-agent számára, amely ezen a projekten dolgozik.
|
||||
> **Minden agent köteles ezt elolvasni és betartani mielőtt bármilyen munkát végez.**
|
||||
|
||||
---
|
||||
|
||||
## 1. Projekt identitás
|
||||
|
||||
- **Projekt neve**: websitedev (mozdIT Bt. weboldal)
|
||||
- **Plane workspace**: `developments` (pm.llmdev.mozdit.hu)
|
||||
- **Plane projekt**: `WebSite Dev` — azonosító: `MITHOME`, ID: `643f7055-1237-4912-912f-99ec49fd0f0e`
|
||||
- **Típus**: Marketing weboldal fejlesztési projekt
|
||||
- **Elsődleges nyelv**: Magyar (kommunikáció, weboldal tartalom, dokumentáció), Angol (kód, kommentek, commit üzenetek)
|
||||
- **Célplatform**: Web (browser-first, mobile-responsive)
|
||||
- **Fő könyvtár**: `proto/` — itt fut a Next.js alkalmazás
|
||||
|
||||
---
|
||||
|
||||
## 2. Steering Documents
|
||||
|
||||
A `.agent/steering/` mappában YAML frontmatterrel ellátott automatikusan betöltődő szabálydokumentumok találhatók:
|
||||
|
||||
- **`development-rules.md`**: Kódolási és workflow szabályok (mindig aktív)
|
||||
- **`architecture.md`**: Rendszerszintű tervezési elvek (mindig aktív)
|
||||
- **`testing.md`**: Tesztelési stratégiák (`tests/**` fájloknál aktív)
|
||||
|
||||
---
|
||||
|
||||
## 3. Alapelvek (Mandatory Principles)
|
||||
|
||||
### 3.1 Kód minőség
|
||||
|
||||
- Mindig olvass el minden érintett fájlt MIELŐTT módosítasz
|
||||
- Soha ne törölj meglévő kódot anélkül, hogy megértenéd annak célját
|
||||
- Minden változtatás legyen **minimális, célzott és indokolt**
|
||||
- Ha bizonytalan vagy, kérdezz — ne találgass
|
||||
|
||||
### 3.2 Konzisztencia
|
||||
|
||||
- Kövess minden meglevő konvenciót, amit a kódbázisban találsz
|
||||
- Ne vezess be új dependency-t jóváhagyás nélkül
|
||||
- Az etablirozott naming convention-t kövesd következetesen
|
||||
|
||||
### 3.3 Dokumentáció
|
||||
|
||||
- Minden új funkció, API endpoint kapjon dokumentációt
|
||||
- Komplex logikát `// WHY:` / `// DECISION:` / `// TRADEOFF:` jelölőkkel láss el
|
||||
- Változtatások után frissítsd az érintett `.md` fájlokat és a `TODO.md`-t
|
||||
|
||||
### 3.4 Biztonság
|
||||
|
||||
- Soha ne commitolj secrets-t, API key-eket, jelszavakat
|
||||
- Minden user input legyen validálva és sanitálva
|
||||
- HTTPS mindenhol, HTTP redirect mindenhol
|
||||
|
||||
### 3.5 Plane szinkronizáció utáni kötelező lépések
|
||||
|
||||
> **KÖTELEZŐ szabály**: Minden feladat státuszváltás után:
|
||||
|
||||
1. **Plane frissítése** — ticket státusz váltás (vagy `node plane-sync.js`)
|
||||
2. **`TODO.md` frissítése** — lokális szinkronban tartás
|
||||
3. **Git commit & push** — az összes módosított fájllal
|
||||
|
||||
**Commit message formátum:**
|
||||
```
|
||||
sync: update Plane issues + TODO [leírás]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Projekt struktúra
|
||||
|
||||
```
|
||||
websitedev/
|
||||
├── proto/ # Fő Next.js alkalmazás (itt futtatsd a parancsokat!)
|
||||
│ ├── src/
|
||||
│ │ ├── app/ # Next.js App Router (pages és API routes)
|
||||
│ │ ├── components/ # React komponensek (Header, Footer, ThemeProvider)
|
||||
│ │ ├── content/ # JSON tartalom-kezelő rendszer
|
||||
│ │ ├── lib/ # Utility könyvtárak (MongoDB, Logger, Site Config)
|
||||
│ │ ├── config/ # Statikus site konfiguráció
|
||||
│ │ └── types/ # TypeScript típusdefiníciók
|
||||
│ └── public/ # Statikus fájlok
|
||||
├── docs/ # Projekt dokumentáció (Magyar)
|
||||
├── .agent/ # AI keretrendszer (NE módosítsd véletlenül)
|
||||
│ ├── steering/ # Auto-betöltődő szabályok
|
||||
│ ├── workflows/ # Slash command workflow-ok
|
||||
│ └── references/ # Ellenőrzőlisták
|
||||
├── scripts/ # Szinkronizáló és reporting scriptek
|
||||
├── TODO.md # Feladat követés (Linear tükörképe)
|
||||
└── linear-sync.js # Linear szinkronizáló script
|
||||
```
|
||||
|
||||
### Forbidden zones
|
||||
|
||||
- `.env` fájlokat SOHA ne commitolj
|
||||
- `node_modules/`, `.next/`, `dist/`, `build/` — csak `.gitignore`-ban
|
||||
|
||||
---
|
||||
|
||||
## 5. Git konvenciók
|
||||
|
||||
### Branch naming
|
||||
|
||||
```
|
||||
feature/[rövid-leírás] → Új funkciók
|
||||
fix/[bug-leírás] → Hibajavítások
|
||||
hotfix/[kritikus-leírás] → Kritikus produkciós javítások
|
||||
refactor/[terület] → Refaktorálás
|
||||
docs/[terület] → Csak dokumentáció
|
||||
chore/[feladat] → Build, deps, tooling
|
||||
```
|
||||
|
||||
### Commit message formátum (Conventional Commits)
|
||||
|
||||
```
|
||||
<type>(<scope>): <rövid leírás>
|
||||
|
||||
[opcionális részletes leírás]
|
||||
|
||||
[opcionális: Closes ZEE-123]
|
||||
```
|
||||
|
||||
**Típusok**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`
|
||||
|
||||
### Példák
|
||||
|
||||
```
|
||||
feat(contact): add rate limiting to contact form API
|
||||
fix(nav): hamburger menu not closing on mobile
|
||||
docs(readme): update deployment instructions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Kódolási szabványok
|
||||
|
||||
### Általános
|
||||
|
||||
- Max line length: **120 karakter**
|
||||
- Indentáció: **2 space** (soha tab)
|
||||
- Trailing whitespace: **tilos**
|
||||
- Fájl végén: **egy newline**
|
||||
|
||||
### Naming conventions
|
||||
|
||||
```
|
||||
fájlok: kebab-case.ts / PascalCase.tsx (komponensek)
|
||||
komponensek: PascalCase
|
||||
függvények: camelCase
|
||||
konstansok: UPPER_SNAKE_CASE
|
||||
CSS osztályok: kebab-case
|
||||
adatbázis: snake_case (gyűjtemény nevek)
|
||||
API endpoint: /kebab-case/:param
|
||||
boolean: is/has/can prefix (pl. isActive, hasPermission)
|
||||
```
|
||||
|
||||
### JavaScript/TypeScript
|
||||
|
||||
- `const`/`let` — soha `var`
|
||||
- Arrow functions preferált
|
||||
- Async/await — soha callback hell
|
||||
- Early return pattern
|
||||
- Explicit error handling — soha silent failures
|
||||
|
||||
### Fájlméret korlátok
|
||||
|
||||
- **Soft limit**: 250–300 sor per fájl
|
||||
- **Hard limit**: 400 sor
|
||||
- Függvény max: **50 sor** (SRP: egy függvény = egy dolog)
|
||||
|
||||
---
|
||||
|
||||
## 7. API konvenciók
|
||||
|
||||
### Response formátum
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": { ... },
|
||||
"meta": {
|
||||
"timestamp": "2026-01-01T00:00:00Z",
|
||||
"version": "1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Human-readable message",
|
||||
"details": [ ... ]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP státusz kódok
|
||||
|
||||
- `200` — Sikeres GET
|
||||
- `201` — Sikeres POST (létrehozás)
|
||||
- `204` — Sikeres DELETE (nincs body)
|
||||
- `400` — Kliens hiba (validáció)
|
||||
- `401` — Nem hitelesített
|
||||
- `403` — Nem jogosult
|
||||
- `404` — Nem található
|
||||
- `500` — Szerver hiba
|
||||
|
||||
---
|
||||
|
||||
## 8. Tesztelési elvek
|
||||
|
||||
### Prioritás
|
||||
|
||||
1. **Unit tesztek** — Pure functions, utilities, business logic
|
||||
2. **Integration tesztek** — API endpoint-ok, DB műveletek
|
||||
3. **E2E tesztek** — Kritikus user flow-ok
|
||||
|
||||
### Coverage elvárás
|
||||
|
||||
- Üzleti logika: **>80%**
|
||||
- Utility függvények: **>90%**
|
||||
- API endpoint-ok: minden happy path + fő error case-ek
|
||||
|
||||
### Futtatás (`proto/` mappából)
|
||||
|
||||
```bash
|
||||
npm test # unit tesztek
|
||||
npm run test:coverage # lefedettség riport
|
||||
npm run test:browser # browser integration
|
||||
npm run test:integration # Docker integration
|
||||
npm run test:all # teljes suite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Intent Capture (Kódkomment konvenciók)
|
||||
|
||||
Komplex logikánál kötelező strukturált kommenteket használni:
|
||||
|
||||
```typescript
|
||||
// WHY: <miért lett így megoldva — motiváció, kényszer>
|
||||
// DECISION: <milyen implementációs kényszert/szabályt követ ez a kód>
|
||||
// TRADEOFF: <mit nyerünk, mit veszítünk ezzel a megközelítéssel>
|
||||
```
|
||||
|
||||
**Mikor kötelező:**
|
||||
- Architektúrális döntésnél
|
||||
- Nem nyilvánvaló logikánál (pl. fire-and-forget pattern)
|
||||
- Ismert trade-off esetén
|
||||
- Ha az alternatívák nem egyértelműek
|
||||
|
||||
---
|
||||
|
||||
## 10. Performance elvek
|
||||
|
||||
- Képek: mindig optimalizált formátumban (WebP, AVIF), Next.js `<Image>` komponenssel
|
||||
- Bundle size: figyelj, lazy loading ahol lehetséges
|
||||
- API válaszidő cél: **<200ms** p95
|
||||
- Lighthouse score cél: **≥90** minden kategóriában
|
||||
|
||||
---
|
||||
|
||||
## 11. Workflow-ok
|
||||
|
||||
Az `.agent/workflows/` mappában találhatók az elérhető slash command workflow-ok:
|
||||
|
||||
| Parancs | Leírás |
|
||||
| --- | --- |
|
||||
| `/new-feature` | Új funkció fejlesztési folyamata |
|
||||
| `/fix-bug` | Hibajavítás folyamata |
|
||||
| `/review` | Kód review checklist |
|
||||
| `/deploy` | Deployment folyamata |
|
||||
|
||||
---
|
||||
|
||||
## 12. References
|
||||
|
||||
Az `.agent/references/` mappában gyorsan alkalmazható ellenőrzőlisták:
|
||||
|
||||
| Reference | Terület |
|
||||
| --- | --- |
|
||||
| `accessibility-checklist.md` | WCAG 2.1 AA — minden UI komponens és oldal esetén |
|
||||
|
||||
---
|
||||
|
||||
## 13. Context Engineering
|
||||
|
||||
### Kontextus mennyiség
|
||||
- Cél: **<2000 sor** legyen egyszerre aktív kontextusban
|
||||
- Csak a jelenlegi task szempontjából releváns fájlokat töltsd be
|
||||
|
||||
### Red Flag-ek (ha ilyeneket tapasztalsz)
|
||||
- Az agent nem létező API-t vagy importot talál ki → kontextus hiány
|
||||
- Output eltér a projekt konvencióitól → steering fájl nincs betöltve
|
||||
- Minőség romlik ahogy a conversation hosszabb lesz → kontextus tömörítés kell
|
||||
|
||||
---
|
||||
|
||||
## 14. Modellválasztás (Model Selection)
|
||||
|
||||
### MCP műveletek — mindig gazdaságos modell
|
||||
|
||||
Az MCP eszközök (Plane issue kezelés, Git műveletek, fájlrendszer lekérdezések) **nem igényelnek erős gondolkodást** — ezekhez mindig a leggazdaságosabb elérhető modellt kell használni:
|
||||
|
||||
| Feladat típusa | Ajánlott modell |
|
||||
| --- | --- |
|
||||
| Plane issue létrehozás/frissítés | Claude Haiku / Gemini Flash |
|
||||
| Git műveletek (commit, push, status) | Claude Haiku / Gemini Flash |
|
||||
| Fájl olvasás, könyvtár listázás | Claude Haiku / Gemini Flash |
|
||||
| TODO.md szinkronizáció | Claude Haiku / Gemini Flash |
|
||||
| **Architektúra, kódírás, tervezés** | **Erősebb modell (Sonnet, Pro)** |
|
||||
| **Komplex debugging, refaktorálás** | **Erősebb modell (Sonnet, Pro)** |
|
||||
|
||||
### Alapelv
|
||||
|
||||
> Az MCP hívások strukturált, determinisztikus műveletek — nem kreatív gondolkodást igényelnek. A drágább modell kapacitását tartsd fenn a tényleges fejlesztési feladatokra.
|
||||
|
||||
---
|
||||
|
||||
## 14. Mikor kérdezz, mikor cselekedj?
|
||||
|
||||
### Cselekedj önállóan ha:
|
||||
|
||||
- A feladat egyértelműen leírja mit kell tenni
|
||||
- Konvenciókat követsz (lásd fent)
|
||||
- Kis, izolált változtatást teszel
|
||||
- Bug fix, amit teljes biztonsággal azonosítottál
|
||||
|
||||
### Kérdezz előbb ha:
|
||||
|
||||
- Architektúrát kell megváltoztatni
|
||||
- Új külső dependency-t vezetnél be
|
||||
- A megoldás több lehetséges irányba mutat
|
||||
- Biztonsági implikációk merülnek fel
|
||||
- Production adatot érintenél
|
||||
|
||||
---
|
||||
|
||||
## 15. Source-Driven Development
|
||||
|
||||
Framework-specifikus kódnál ne emlékezetből dolgozz — a dokumentációt olvasd.
|
||||
|
||||
### Forrás-hierarchia (csökkenő megbízhatóság)
|
||||
1. **Hivatalos dokumentáció** (nextjs.org, react.dev, mongoosejs.com, stb.)
|
||||
2. **Hivatalos blog / changelog** (breaking changes, migration guide-ok)
|
||||
3. **Web szabványok** (MDN, web.dev)
|
||||
|
||||
**Soha ne elsődleges forrásként:** Stack Overflow, tutorialok, AI összefoglalók.
|
||||
|
||||
---
|
||||
|
||||
*Utoljára frissítve: 2026-04-26 | Verzió: 1.0.0 — Szintetizálva a tipruc AGENTS.md (v1.3.0) és a websitedev CLAUDE.md alapján*
|
||||
@@ -0,0 +1,81 @@
|
||||
# Accessibility Checklist (WCAG 2.1 AA)
|
||||
|
||||
Minden böngészős felület esetén kötelező ellenőrzőlista.
|
||||
Az accessibility jogi követelmény és mérnöki minőségi standard.
|
||||
Cél: **Lighthouse accessibility score ≥90** minden deploy előtt.
|
||||
|
||||
---
|
||||
|
||||
## Keyboard és navigáció
|
||||
|
||||
- [ ] Minden interaktív elem elérhető Tab-bal
|
||||
- [ ] Látható focus indikátor minden fókuszálható elemen (`:focus-visible`)
|
||||
- [ ] Nincs keyboard trap (el lehet navigálni minden elemről)
|
||||
- [ ] Skip-to-content link az oldal tetején (hosszú nav esetén)
|
||||
- [ ] Mobil hamburger menü: Escape bezárja, fókusz visszatér
|
||||
|
||||
## Screen reader támogatás
|
||||
|
||||
- [ ] Képek: alt text (informatív képeknél), üres alt dekoratív képeknél (`alt=""`)
|
||||
- [ ] Form input-ok: minden inputhoz tartozik látható `<label>`
|
||||
- [ ] Oldal struktúra: egy `<h1>`, heading szintek nem ugranak át
|
||||
- [ ] Dinamikus tartalom: `aria-live` region frissítésekhez (pl. form sikerüzenet)
|
||||
- [ ] Ikonok szöveg nélkül: `aria-label` vagy `aria-hidden="true"` + látható szöveg
|
||||
|
||||
## Vizuális elvárások
|
||||
|
||||
- [ ] Szöveg kontraszt: **4.5:1** minimum (normál szöveg), **3:1** (nagy szöveg ≥18px / bold ≥14px)
|
||||
- [ ] Szín nem az egyetlen információhordozó (pl. hiba jelzés: szín + ikon + szöveg)
|
||||
- [ ] Nem villog semmi 3x/sec-nél gyorsabban
|
||||
- [ ] Szöveg 200%-ra zoomolható törés nélkül
|
||||
- [ ] Sötét módban is megfelelő a kontraszt
|
||||
|
||||
## Formok és tartalom
|
||||
|
||||
- [ ] Minden input: látható label (nem csak placeholder)
|
||||
- [ ] Kötelező mező jelzése nem csak színnel (pl. csillag + szöveg)
|
||||
- [ ] Hibaüzenet: konkrét, az érintett mezőhöz rendelve (`aria-describedby`)
|
||||
- [ ] Touch target méret: legalább **44×44px**
|
||||
- [ ] GDPR checkbox: megfelelő label és accessible hibaüzenet
|
||||
|
||||
## Komponens anti-patternek (kerülendő)
|
||||
|
||||
- `<div>` vagy `<span>` gomb helyett — használj `<button>`
|
||||
- `outline: none` focus eltávolítása CSS-ben vizuális helyettesítő nélkül
|
||||
- Csak szín alapú állapotjelzés (aktív, hiba, sikeres)
|
||||
- Hibás `tabindex` értékek (pozitív tabindex-et kerüld)
|
||||
- `aria-hidden="true"` fókuszálható elemen
|
||||
|
||||
---
|
||||
|
||||
## Tesztelési eszközök
|
||||
|
||||
- **jest-axe** — automatizált a11y teszt a unit tesztekben (kötelező minden új komponenshez)
|
||||
- **axe DevTools** (Chrome extension) — manuális WCAG ellenőrzés
|
||||
- **Lighthouse accessibility audit** — beépített Chrome DevTools (cél: ≥90)
|
||||
- **Manuális keyboard navigáció** — Tab, Shift+Tab, Enter, Space, Escape, Arrow keys
|
||||
- **Screen reader teszt** — VoiceOver (macOS/iOS)
|
||||
|
||||
---
|
||||
|
||||
## jest-axe példa
|
||||
|
||||
```typescript
|
||||
import { render } from '@testing-library/react'
|
||||
import { axe, toHaveNoViolations } from 'jest-axe'
|
||||
import MyComponent from '@/components/MyComponent'
|
||||
|
||||
expect.extend(toHaveNoViolations)
|
||||
|
||||
describe('MyComponent accessibility', () => {
|
||||
it('should have no accessibility violations', async () => {
|
||||
const { container } = render(<MyComponent />)
|
||||
const results = await axe(container)
|
||||
expect(results).toHaveNoViolations()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
WCAG 2.1 AA szint a projekt minimuma.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
inclusion: auto
|
||||
---
|
||||
|
||||
# Rendszerépítési Irányelvek (Architecture Steering)
|
||||
|
||||
Ez a fájl minden interakcióban automatikusan betöltődik az AI számára a projekt konzisztenciájának biztosítása érdekében.
|
||||
|
||||
## Rendszer áttekintés
|
||||
|
||||
A projekt egy **Next.js 15 alapú marketing weboldal** a mozdIT Bt. számára, App Router architektúrával, TypeScript-tel és Tailwind CSS 4-gyel.
|
||||
|
||||
- **Frontend**: Next.js 15 App Router (SSR/SSG), React 19, Tailwind CSS 4
|
||||
- **Backend**: Next.js API Routes (`/api/*`)
|
||||
- **Adatbázis**: MongoDB (Mongoose ODM) — site config és contact form logok
|
||||
- **Logging**: Winston + Loki (strukturált naplózás)
|
||||
- **Infrastructure**: Docker + Docker Compose, Dokploy deployment
|
||||
|
||||
## Rétegek és Felelősségek
|
||||
|
||||
| Réteg | Felelősség | Helye |
|
||||
| --- | --- | --- |
|
||||
| **Page** | Oldal-szintű komponensek, SSR/SSG | `proto/src/app/` |
|
||||
| **Component** | Újrahasználható UI elemek | `proto/src/components/` |
|
||||
| **API Route** | Route handling, validáció | `proto/src/app/api/` |
|
||||
| **Service/Lib** | Üzleti logika, DB kapcsolat | `proto/src/lib/` |
|
||||
| **Content** | JSON alapú tartalom | `proto/src/content/` |
|
||||
| **Config** | Statikus site konfiguráció | `proto/src/config/` |
|
||||
| **Agent / Tools** | AI ügynökök eszközei | `.agent/` |
|
||||
|
||||
## Fontos Architektúra Szabályok
|
||||
|
||||
1. **Tartalom JSON-ban**: SOHA ne égess be szöveget közvetlenül komponensbe — használd a `src/content/` rendszert.
|
||||
2. **Stateless API**: A backend API teljesen stateless — session-t a kliens kezel.
|
||||
3. **Observability**: Minden hiba legyen logolva Winstonnal. API válaszok egységes formátumban: `{ success, data, error }`.
|
||||
4. **Security-by-design**: Input validáció minden API route-on, secrets csak env változókból.
|
||||
5. **Component-first**: Komponensek Server Component-ek alapértelmezetten — csak indokolt esetben adj `"use client"` direktívát.
|
||||
|
||||
## Adatfolyam (Request Lifecycle)
|
||||
|
||||
1. **Dokploy / Nginx**: SSL, rate limit (infra szint)
|
||||
2. **Next.js middleware**: Auth ellenőrzés (ha szükséges)
|
||||
3. **API Route**: Input validáció
|
||||
4. **Lib/Service**: Üzleti logika végrehajtása
|
||||
5. **MongoDB**: Adatbázis művelet
|
||||
6. **Responder**: Egységes formátumú JSON válasz
|
||||
|
||||
## Design System szabályok
|
||||
|
||||
- CSS változók (`globals.css`) — ne írj keménykódolt színértékeket
|
||||
- Dark mode: `ThemeProvider` komponensen keresztül — ne írj `dark:` Tailwind osztályokat közvetlen, ha a ThemeProvider kezeli
|
||||
- Animációk: `globals.css`-ben definiált utility osztályok (`.card`, `.btn`, `.icon-container`)
|
||||
- Reszponzivitás: mobile-first, breakpoint-ok: 360px, 640px, 768px, 1024px, 1280px+
|
||||
|
||||
## Content Management
|
||||
|
||||
```typescript
|
||||
// Helyes: content rendszer használata
|
||||
import { content, getPageContent } from '@/content'
|
||||
const pageData = content.pages.about
|
||||
|
||||
// TILOS: közvetlen szöveg komponensben
|
||||
<h1>Rólunk</h1>
|
||||
```
|
||||
|
||||
## Dependency szabályok
|
||||
|
||||
- Új NPM package bevezetéséhez **jóváhagyás szükséges**
|
||||
- Előnyben részesítjük a Next.js beépített megoldásait (Image, Link, Font, stb.)
|
||||
- MongoDB driver helyett Mongoose ODM-et használunk
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
inclusion: auto
|
||||
---
|
||||
|
||||
# Fejlesztési Szabályok (Development Steering)
|
||||
|
||||
Ez a fájl minden interakcióban automatikusan betöltődik, és meghatározza a kódolási és workflow elvárásokat.
|
||||
|
||||
## Fájlméret és Egységek (Granularity)
|
||||
|
||||
- **Soft limit**: 250–300 sor per fájl.
|
||||
- **Hard limit**: 400 sor.
|
||||
- Ha egy fájl eléri a 300 sort, kötelező kisebb modulokra, service-ekre vagy utility-kre bontani.
|
||||
- A függvények mérete ne haladja meg az **50 sort**. Egy függvény egy dolgot csináljon (SRP).
|
||||
|
||||
## Könyvtárstruktúra és Naming
|
||||
|
||||
A projekt a következő konvenciókat követi:
|
||||
|
||||
- **Fájlnevek (általános)**: `kebab-case.extension` (pl. `site-config.ts`, `mongodb.ts`)
|
||||
- **Komponens fájlok**: `PascalCase.tsx` (pl. `Header.tsx`, `ThemeProvider.tsx`) — Next.js/React konvenció
|
||||
- **Mappák**: `kebab-case/`
|
||||
- **Osztályok/Komponensek**: `PascalCase`
|
||||
- **Függvények/Változók**: `camelCase`
|
||||
- **Konstansok**: `UPPER_SNAKE_CASE`
|
||||
- **Boolean**: `is/has/can` prefix (pl. `isActive`, `hasPermission`)
|
||||
- **CSS osztályok**: `kebab-case`
|
||||
- **API endpoint-ok**: `/kebab-case/:param`
|
||||
|
||||
## Task Tracking (Kötelező)
|
||||
|
||||
- Minden feladat a **gyökér `TODO.md`-ben** kerül nyilvántartásra, Linear ticketekre hivatkozva (ZEE-* sorozat).
|
||||
- A `linear-sync.js` scripttel tartjuk szinkronban a Linear-t és a TODO.md-t.
|
||||
- Soha ne hozz létre párhuzamos feladatlistát vagy külön tasks/ mappát — ez a projekt `TODO.md` + Linear kombinációt használ.
|
||||
- **Feladat státuszok TODO.md-ben**: `📋 Tervezett` → `🔄 Folyamatban` → `✅ Kész`
|
||||
|
||||
## Szinkronizáció utáni kötelező lépések
|
||||
|
||||
> **KÖTELEZŐ**: Minden feladat befejezése vagy státuszváltás után:
|
||||
|
||||
1. Frissítsd a **Linear ticket** státuszát
|
||||
2. Frissítsd a **`TODO.md`**-t
|
||||
3. `git add . && git commit -m "sync: ..."` + push
|
||||
|
||||
## Specifikáció Alapú Fejlesztés
|
||||
|
||||
Nagyobb funkciókhoz a `docs/` mappában dolgozd ki:
|
||||
|
||||
- `requirements.md`: user story-k és elfogadási kritériumok
|
||||
- API vagy adatmodell változásnál: frissítsd a `REQUIREMENTS-CATALOG.md`-t
|
||||
|
||||
### Task formátumok (TODO.md-ben)
|
||||
|
||||
```markdown
|
||||
| ZEE-XXX | Feladat neve | 📋 Tervezett |
|
||||
| ZEE-XXX | Feladat neve | 🔄 Folyamatban |
|
||||
| ZEE-XXX | Feladat neve | ✅ Kész |
|
||||
```
|
||||
|
||||
- Minden tasknak legyen elfogadási kritériuma mielőtt belekezdünk.
|
||||
- Task befejezés előtt fuss tesztet.
|
||||
|
||||
## Bugfix Módszertan (Szigorú 3 Fázis)
|
||||
|
||||
Kritikus hibák javításánál az alábbi sorrendet KÖTELEZŐ követni:
|
||||
|
||||
1. **Felfedező tesztek (Exploration tests — JAVÍTÁS ELŐTT)**: Írj teszteket, amelyek ELBUKNAK a hibás kódon (ez bizonyítja a hibát). Ne módosítsd még a kódot.
|
||||
2. **Megőrző tesztek (Preservation tests — JAVÍTÁS ELŐTT)**: Írj teszteket, amelyek még a hibás kódon is ÁTMENNEK. Ezek garantálják, hogy a javítás során a jó funkciók nem sérülnek.
|
||||
3. **Javítás + Ellenőrzés**: Javítsd a kódot. A felfedező teszteknek most zöldnek kell lenniük, a megőrző tesztek továbbra is zöldek.
|
||||
|
||||
## Bugfix Git konvenció
|
||||
|
||||
```bash
|
||||
git commit -m "fix(<scope>): <mi volt a hiba és hogyan lett javítva>"
|
||||
```
|
||||
|
||||
## Nyelvhasználat
|
||||
|
||||
- **Kód, kommentek, commit üzenetek**: Angol
|
||||
- **Technikai dokumentáció**: Magyar (weboldal szövegek, docs/, TODO.md)
|
||||
- **Kommunikáció a felhasználóval**: Magyar
|
||||
|
||||
## Async konvenciók
|
||||
|
||||
- Kerüld a callback-hellt.
|
||||
- Használj `async/await` szerkezetet mindenhol, ahol I/O művelet történik.
|
||||
- Hibakezelésnél soha ne „nyeld el" a hibát (silent fail).
|
||||
|
||||
## Task Breakdown minőségi elvárások
|
||||
|
||||
Minden feladatbontásnál:
|
||||
|
||||
- **Task méret**: Small (1–2 fájl) vagy Medium (3–5 fájl) az ideális. 8+ fájl egyetlen taskban → rossz dekompozíció, bontsd kisebbre.
|
||||
- **Vertical slices**: Minden task szállítson egy teljes, end-to-end működő szeletet — ne horizontal layer-eket.
|
||||
- **Acceptance criteria kötelező**: pl. nem „implement contact form" — hanem „implement contact form with validation, rate limiting, >80% coverage".
|
||||
- **Verification lépés kötelező**: Minden task végén fusson teszt vagy manuális ellenőrzés.
|
||||
|
||||
### Red Flag-ek (ha ezeket látod, állj meg)
|
||||
- Nincs írott task lista mielőtt kódot írsz
|
||||
- Egy task >8 fájlt érint
|
||||
- Nincs acceptance criteria
|
||||
- Nincs verification lépés
|
||||
|
||||
## Kódkomment konvenciók (Intent Capture)
|
||||
|
||||
```typescript
|
||||
// WHY: <miért lett így megoldva — motiváció, kényszer>
|
||||
// DECISION: <milyen implementációs kényszert/szabályt követ ez a kód>
|
||||
// TRADEOFF: <mit nyerünk, mit veszítünk ezzel a megközelítéssel>
|
||||
```
|
||||
|
||||
### Mikor kötelező
|
||||
- Architektúrális döntésnél (pl. miért MongoDB és nem egyszerű fájl)
|
||||
- Nem nyilvánvaló logikánál (pl. rate limiting implementáció)
|
||||
- Ismert trade-off esetén (pl. teljesítmény vs. egyszerűség)
|
||||
- Ha az alternatívák nem egyértelműek
|
||||
|
||||
### Példák
|
||||
|
||||
```typescript
|
||||
// WHY: in-memory rate limiting — elegendő egyetlen instance esetén, nem igényel Redis-t
|
||||
const rateLimitStore = new Map<string, number[]>();
|
||||
|
||||
// DECISION: fire-and-forget MongoDB write — ne várakozzon a válasz a cache írásra
|
||||
dbClient.logContact(data).catch(() => null);
|
||||
|
||||
// TRADEOFF: JSON content management vs CMS — könnyebb deploy, de nem non-tech szerkeszthető
|
||||
const content = await import('@/content/pages/home.json');
|
||||
```
|
||||
|
||||
## Pre-modification kockázatbecslés
|
||||
|
||||
Mielőtt egy meglévő fájlhoz nyúlsz:
|
||||
|
||||
**Impact radius — hány fájl importálja?**
|
||||
```bash
|
||||
grep -r "from.*<modul-neve>" proto/src/ --include="*.ts" --include="*.tsx" -l
|
||||
```
|
||||
Ha 5+ fájl importálja: a módosítás kockázatos, tartsd visszafele kompatibilisnek.
|
||||
|
||||
**Tesztlefedettség — van-e tesztje?**
|
||||
Ha nincs `<fájlnév>.test.ts`: módosítás előtt írj preservation teszteket.
|
||||
|
||||
**Érzékeny terület?**
|
||||
Ha a fájl tartalmaz `auth`, `password`, `api-key` jellegű logikát → különös gondossággal kezelj.
|
||||
|
||||
## Source-Driven Development
|
||||
|
||||
Framework-specifikus kódnál ne emlékezetből dolgozz.
|
||||
|
||||
### Forrás-hierarchia (csökkenő megbízhatóság)
|
||||
1. **Hivatalos dokumentáció** (nextjs.org, react.dev, mongoosejs.com, stb.)
|
||||
2. **Hivatalos blog / changelog** (breaking changes, migration guide-ok)
|
||||
3. **Web szabványok** (MDN, web.dev)
|
||||
|
||||
**Soha ne elsődleges forrásként:** Stack Overflow, tutorialok, AI összefoglalók.
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
inclusion: fileMatch
|
||||
fileMatchPattern: "proto/src/**/*.test.*"
|
||||
---
|
||||
|
||||
# Tesztelési Irányelvek (Testing Steering)
|
||||
|
||||
Ez a fájl automatikusan betöltődik tesztfájlok érintésekor, és segít a tesztelési stratégia betartásában.
|
||||
|
||||
## Stratégia és Prioritások
|
||||
|
||||
1. **Unit tesztek**: Logikai egységek, tiszta függvények, komponensek tesztelése (`jest.config.unit.js`)
|
||||
2. **Browser integration**: jsdom + mocked API-k (`jest.config.js`)
|
||||
3. **Docker integration**: Valódi HTTP hívások a futó Docker stack-hez (`jest.config.integration.js`)
|
||||
4. **E2E tesztek**: Teljes user flow-ok (`src/__tests__/e2e-docker.test.ts`)
|
||||
|
||||
## Elvárások
|
||||
|
||||
- **Minden új funkcióhoz** kötelező tesztet írni.
|
||||
- **Kódlefedettség (Coverage)**:
|
||||
- Üzleti logika (`lib/`, service-ek): **>80%**
|
||||
- Utility függvények: **>90%**
|
||||
- API endpoint-ok: minden happy path + fő error case-ek
|
||||
- A tesztek legyenek **izoláltak** és **determinisztikusak**.
|
||||
- Használj mock-okat a külső függőségekhez (MongoDB, Loki, HTTP hívások).
|
||||
|
||||
## Elnevezési konvenciók
|
||||
|
||||
- Tesztfájlok: `filename.test.ts` / `Component.test.tsx`
|
||||
- Teszt nevek: Describe what it **should** do:
|
||||
```
|
||||
✅ "should return 400 if email is invalid"
|
||||
❌ "test email validation"
|
||||
```
|
||||
- Integráció tesztek: `__tests__/integration.test.ts`
|
||||
- E2E tesztek: `__tests__/e2e-docker.test.ts`
|
||||
|
||||
## Futtatás (`proto/` mappából)
|
||||
|
||||
```bash
|
||||
npm test # unit tesztek (alapértelmezett)
|
||||
npm run test:watch # watch mode
|
||||
npm run test:coverage # lefedettség riport
|
||||
npm run test:browser # browser integration
|
||||
npm run test:integration # Docker integration (Docker kell!)
|
||||
npm run test:e2e # E2E tesztek (Docker kell!)
|
||||
npm run test:all # teljes suite
|
||||
npm run test:report # tesztek + Linear szinkron riport
|
||||
```
|
||||
|
||||
## Bugfix tesztelési sorrend (kötelező)
|
||||
|
||||
1. **Exploration test** (JAVÍTÁS ELŐTT): Bukjon el a hibás kódon
|
||||
2. **Preservation test** (JAVÍTÁS ELŐTT): Menjen át a hibás kódon is
|
||||
3. **Javítás**: Az exploration test legyen zöld, preservation maradjon zöld
|
||||
|
||||
## Accessibility tesztelés
|
||||
|
||||
- Minden új React komponenshez kötelező `jest-axe` a11y teszt:
|
||||
```typescript
|
||||
import { axe, toHaveNoViolations } from 'jest-axe'
|
||||
expect.extend(toHaveNoViolations)
|
||||
|
||||
it('should have no accessibility violations', async () => {
|
||||
const { container } = render(<MyComponent />)
|
||||
const results = await axe(container)
|
||||
expect(results).toHaveNoViolations()
|
||||
})
|
||||
```
|
||||
- Lighthouse accessibility score: **≥90** — minden deploy előtt ellenőrizd.
|
||||
|
||||
## Gherkin és Linear riporting
|
||||
|
||||
A projekt automatikus teszt-riportot tud generálni Gherkin formátumban és Linear-ba szinkronizálni:
|
||||
|
||||
```bash
|
||||
npm run test:gherkin # Gherkin riport generálás
|
||||
npm run test:update-tc # Linear TC issue-k frissítése
|
||||
npm run test:full-report # mindkettő egyszerre
|
||||
```
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
description: Deployment munkafolyamata — lokális teszttől a produkciós deployig
|
||||
---
|
||||
|
||||
# Deploy Workflow (/deploy)
|
||||
|
||||
## Előfeltételek
|
||||
- Minden teszt zöld: `cd proto && npm run test:all`
|
||||
- Lint hibamentes: `cd proto && npm run lint`
|
||||
- `TODO.md` és Linear up-to-date
|
||||
|
||||
---
|
||||
|
||||
## Lépések
|
||||
|
||||
### 1. Pre-deploy ellenőrzés
|
||||
```bash
|
||||
cd proto
|
||||
npm run lint # nincs lint hiba
|
||||
npm test # unit tesztek zöldek
|
||||
npm run build # build sikeres-e?
|
||||
```
|
||||
|
||||
### 2. Staging deploy
|
||||
A Dokploy automatikusan buildi és deployolja a `main` branchre kerülő commitokat:
|
||||
- **Staging**: https://staging.mozdit.hu
|
||||
|
||||
Ellenőrizd stagingen:
|
||||
- [ ] Főbb oldalak betöltenek (/, /rolunk, /szolgaltatasok, /kapcsolat)
|
||||
- [ ] Kapcsolat form működik
|
||||
- [ ] Sötét mód vált
|
||||
- [ ] Mobil nézet rendben
|
||||
- [ ] `/api/health` endpoint zöld
|
||||
|
||||
### 3. Produkciós deploy
|
||||
Ha staging rendben van, a produkciós deploy Dokploy-on keresztül történik:
|
||||
- **Production**: https://mozdit.hu
|
||||
|
||||
### 4. Post-deploy ellenőrzés
|
||||
- [ ] Minden oldal betölt production-ban
|
||||
- [ ] `/api/health` endpoint ellenőrzése
|
||||
- [ ] Lighthouse futtatás (≥90 minden kategóriában)
|
||||
- [ ] Grafana dashboardon nincsenek hibák
|
||||
|
||||
### 5. Rollback (ha szükséges)
|
||||
Dokploy felületen az előző deploy visszaállítható.
|
||||
|
||||
---
|
||||
|
||||
## Docker lokális stack
|
||||
|
||||
```bash
|
||||
# Teljes stack indítása (Next.js + MongoDB + Grafana + Loki)
|
||||
cd proto && npm run docker:dev
|
||||
|
||||
# Leállítás
|
||||
npm run docker:dev:down
|
||||
|
||||
# Logok követése
|
||||
npm run docker:dev:logs
|
||||
```
|
||||
|
||||
Elérhető szolgáltatások:
|
||||
- **Weboldal**: http://localhost:3000
|
||||
- **MongoDB UI**: http://localhost:8081 (admin/password123)
|
||||
- **Grafana**: http://localhost:3001 (admin/admin123)
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
description: Hibajavítás munkafolyamata — azonosítástól a commitig
|
||||
---
|
||||
|
||||
# Bug Fix Workflow (/fix-bug)
|
||||
|
||||
## Előfeltételek
|
||||
- Reprodukálható a hiba? Ha nem: gather more info
|
||||
- Ismert-e a root cause? Ha nem: debug először
|
||||
|
||||
---
|
||||
|
||||
## Lépések
|
||||
|
||||
### 1. Hibaazonosítás
|
||||
- Reprodukáld a hibát lokálisan (`cd proto && npm run dev`)
|
||||
- Nézd meg a logokat: Winston logger output, browser console
|
||||
- Azonosítsd az érintett kódrészt
|
||||
- Értsd meg a **root cause**-t (ne csak a tünetet!)
|
||||
|
||||
### 2. Branch létrehozás
|
||||
```bash
|
||||
git checkout -b fix/[rövid-hiba-leírás]
|
||||
```
|
||||
|
||||
### 3. Exploration teszt írása ELŐSZÖR (TDD — kötelező)
|
||||
Írj egy tesztet, ami **megbukik** a jelenlegi hibás kódon:
|
||||
```bash
|
||||
cd proto && npm test -- --testNamePattern="[teszt neve]"
|
||||
```
|
||||
A piros szín bizonyítja, hogy a hibát megértetted.
|
||||
|
||||
### 4. Preservation tesztek írása
|
||||
Írj teszteket, amelyek a **jelenlegi hibás kódon is átmennek** — ezek garantálják, hogy a javítás nem töri el a működő részeket.
|
||||
|
||||
### 5. Javítás implementálása
|
||||
- Minimális, célzott változtatás
|
||||
- Ne refaktorálj egyszerre (külön commit/PR)
|
||||
- Tartsd szem előtt: mi okozta a hibát? Ne csak a tünetet kezeld!
|
||||
|
||||
### 6. Tesztek futtatása
|
||||
```bash
|
||||
cd proto && npm test
|
||||
```
|
||||
- Az exploration teszt zöld lett?
|
||||
- A preservation tesztek továbbra is zöldek?
|
||||
- Más tesztek nem törtek el?
|
||||
|
||||
### 7. Regressziós ellenőrzés
|
||||
- Futtasd a teljes test suite-ot: `npm run test:all`
|
||||
- Manuálisan is ellenőrizd az érintett területet
|
||||
- Mobil és dark mode nézet ellenőrzése (ha UI-t érintett)
|
||||
|
||||
### 8. Commit
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "fix(<scope>): <mi volt a hiba és hogyan lett javítva>"
|
||||
git push origin fix/[hiba-leírás]
|
||||
```
|
||||
|
||||
### 9. Dokumentálás (ha általánosabb tanulság)
|
||||
- Ha érdekes/nem nyilvánvaló bug volt: adj `// WHY:` kommentet a javításhoz
|
||||
- Frissítsd a `TODO.md`-t és a Linear ticketet
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
description: Új feature fejlesztési munkafolyamata — tervezéstől a kész implementációig
|
||||
---
|
||||
|
||||
# Új Feature Fejlesztési Workflow (/new-feature)
|
||||
|
||||
## Előfeltételek
|
||||
- Ismerd a ZEE ticket leírását pontosan
|
||||
- Olvasd el az `AGENTS.md`-t és a releváns steering fájlokat
|
||||
- Ellenőrizd a `TODO.md`-t — nincs-e már ilyen feladat?
|
||||
|
||||
---
|
||||
|
||||
## Lépések
|
||||
|
||||
### 0. Assumptions-first és scope meghatározás (KÖTELEZŐ első lépés)
|
||||
|
||||
Mielőtt bármilyen kódhoz nyúlsz, írd le explicit módon:
|
||||
|
||||
**Feltételezések listája:**
|
||||
- Mi az, amit feltételezünk a requirements-ről?
|
||||
- Milyen technikai döntéseket hozunk és miért?
|
||||
- Mire támaszkodunk (meglévő lib, content rendszer, MongoDB schema)?
|
||||
|
||||
**"Not Doing" lista:**
|
||||
- Mi az, ami *nem* része ennek a feature-nek?
|
||||
- Milyen edge case-eket *szándékosan* kihagyunk most?
|
||||
- Mi kerül a backlogba?
|
||||
|
||||
> Kommunikáld a felhasználónak jóváhagyásra, mielőtt továbblép a fejlesztésre.
|
||||
|
||||
### 0.5. Pre-modification kockázatbecslés (meglévő fájl érintésekor)
|
||||
|
||||
**Impact radius — hány fájl importálja?**
|
||||
```bash
|
||||
grep -r "from.*<modul-neve>" proto/src/ --include="*.ts" --include="*.tsx" -l
|
||||
```
|
||||
Ha 5+ fájl importálja: tartsd visszafele kompatibilisnek.
|
||||
|
||||
**Tesztlefedettség — van-e tesztje?**
|
||||
Ha nincs `<fájlnév>.test.ts`: módosítás előtt írj preservation teszteket.
|
||||
|
||||
**Érzékeny terület?**
|
||||
Ha a fájl `auth`, `password`, `api-key` logikát tartalmaz → különös gondossággal.
|
||||
|
||||
### 1. Feladat megértés és tervezés
|
||||
- Értsd meg pontosan mit kell megvalósítani
|
||||
- Azonosítsd az érintett rétegeket (Page / Component / API / Lib / Content)
|
||||
- Tervezd meg az adatmodellt (ha szükséges)
|
||||
- Ha valami nem egyértelmű: **kérdezz előbb!**
|
||||
|
||||
### 2. Branch létrehozás
|
||||
```bash
|
||||
git checkout -b feature/[leíró-feature-neve]
|
||||
```
|
||||
|
||||
### 3. Content frissítés (ha szöveges tartalom kell)
|
||||
- Módosítsd a megfelelő `proto/src/content/pages/*.json` fájlt
|
||||
- Frissítsd a `types.ts`-t ha új content struktúra kell
|
||||
|
||||
### 4. UI / Komponens implementáció (ha szükséges)
|
||||
- Server Component alapértelmezetten — csak indokolt esetben `"use client"`
|
||||
- Legkisebb komponenstől haladj az oldal felé
|
||||
- Reszponzivitás beépítve (mobile-first)
|
||||
- Accessibility ellenőrzés (lásd `.agent/references/accessibility-checklist.md`)
|
||||
- Design system: CSS változók és utility osztályok, nem hardcoded értékek
|
||||
|
||||
### 5. API Route implementáció (ha szükséges)
|
||||
- Input validáció minden esetben
|
||||
- Egységes response formátum: `{ success, data, error }`
|
||||
- Rate limiting érzékeny endpoint-okon
|
||||
- Winston logging hibák esetén
|
||||
|
||||
### 6. Tesztek írása
|
||||
- Unit tesztek (lib logika, component render)
|
||||
- API endpoint tesztek (happy path + fő error case-ek)
|
||||
- Accessibility teszt (jest-axe) minden új komponenshez
|
||||
|
||||
### 7. Manuális ellenőrzés
|
||||
- Futtasd a feature-t lokálisan (`cd proto && npm run dev`)
|
||||
- Happy path + edge case-ek
|
||||
- Mobil nézetben is ellenőrizd
|
||||
- Sötét módban is ellenőrizd
|
||||
|
||||
### 8. Dokumentáció frissítése
|
||||
- Frissítsd a `TODO.md`-t (státusz: ✅ Kész)
|
||||
- Ha új API endpoint: frissítsd a `REQUIREMENTS-CATALOG.md`-t
|
||||
- Inline `// WHY:` / `// DECISION:` kommentek komplex részekre
|
||||
|
||||
### 9. Commit és push
|
||||
```bash
|
||||
npm test # minden tesztet futtass!
|
||||
git add .
|
||||
git commit -m "feat(<scope>): <rövid leírás>"
|
||||
git push origin feature/[feature-neve]
|
||||
```
|
||||
|
||||
### 10. Linear szinkron
|
||||
- Frissítsd a Linear ticket státuszát
|
||||
- `node linear-sync.js` ha szükséges
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
description: Kód review checklist — PR előtt és review során
|
||||
---
|
||||
|
||||
# Code Review Workflow (/review)
|
||||
|
||||
## Mikor használd
|
||||
- PR megnyitása előtt (önellenőrzés)
|
||||
- Agent-generált kód ellenőrzésekor
|
||||
|
||||
---
|
||||
|
||||
## Önellenőrzés checklist (PR megnyitása előtt)
|
||||
|
||||
### Általános
|
||||
- [ ] A kód megoldja a feladatot?
|
||||
- [ ] Nincs felesleges `console.log`, debug kód?
|
||||
- [ ] Nincs commitolt `.env` vagy secret?
|
||||
- [ ] A változtatások minimálisak és célzottak?
|
||||
- [ ] Nincs hardcoded szöveg komponensben (content JSON-ból jön)?
|
||||
|
||||
### Kód minőség
|
||||
- [ ] Érthetők a változónevek?
|
||||
- [ ] Nincs felesleges duplikáció (DRY)?
|
||||
- [ ] Komplex logika `// WHY:` / `// DECISION:` kommentekkel ellátva?
|
||||
- [ ] Minden edge case le van kezelve?
|
||||
- [ ] Error handling megfelelő (nincs silent fail)?
|
||||
- [ ] Fájlméret <400 sor? Függvény <50 sor?
|
||||
|
||||
### Tesztek
|
||||
- [ ] Vannak tesztek az új kódhoz?
|
||||
- [ ] Minden teszt zöld (`cd proto && npm test`)?
|
||||
- [ ] Coverage nem csökkent?
|
||||
|
||||
### UX minőség (frontend érintésekor)
|
||||
- [ ] `jest-axe` a11y teszt megvan az új komponensekhez?
|
||||
- [ ] Lighthouse accessibility score ≥90?
|
||||
- [ ] Loading / error / empty állapotok le vannak kezelve?
|
||||
- [ ] Keyboard navigáció működik az új elemeken?
|
||||
- [ ] Touch target méretek legalább 44×44px?
|
||||
- [ ] Sötét módban is megfelelő a megjelenés?
|
||||
- [ ] Mobil nézetben is ellenőrizve?
|
||||
|
||||
### Biztonság
|
||||
- [ ] Nincs user input escaped/validált nélkül?
|
||||
- [ ] Nincs érzékeny adat logolva?
|
||||
- [ ] Rate limiting érzékeny endpoint-okon?
|
||||
|
||||
### Teljesítmény
|
||||
- [ ] Képek Next.js `<Image>` komponenssel és WebP/AVIF formátumban?
|
||||
- [ ] Nincs felesleges re-render?
|
||||
- [ ] Server Component-ek ahol lehetséges (`"use client"` minimalizálva)?
|
||||
|
||||
### Dokumentáció
|
||||
- [ ] `TODO.md` frissítve?
|
||||
- [ ] Linear ticket státusza frissítve?
|
||||
- [ ] API változás esetén `REQUIREMENTS-CATALOG.md` frissítve?
|
||||
|
||||
---
|
||||
|
||||
## Review visszajelzés típusok
|
||||
|
||||
- **[BLOCK]** — Blokkoló, meg kell javítani commit előtt
|
||||
- **[SUGGEST]** — Javaslat, nem blokkoló
|
||||
- **[QUESTION]** — Megértési vagy design döntés kérdése
|
||||
- **[NITPICK]** — Apróság, ha nem zavar ne változtass
|
||||
- **[PRAISE]** — Dicséretre érdemes megoldás ✨
|
||||
|
||||
## Jó review komment mintái
|
||||
|
||||
```
|
||||
❌ ROSSZ:
|
||||
"Ez rossz."
|
||||
|
||||
✅ JÓ:
|
||||
[BLOCK] Ez hardcoded szöveget tartalmaz a komponensben.
|
||||
Át kell tenni: proto/src/content/pages/home.json → content.pages.home.*
|
||||
|
||||
[SUGGEST] Ezt a logikát érdemes egy helper funkcióba kiszervezni,
|
||||
ha több helyen is szükség lesz rá.
|
||||
|
||||
[QUESTION] Miért Server Component itt? A state miatt "use client" kellene?
|
||||
```
|
||||
@@ -1,429 +0,0 @@
|
||||
/**
|
||||
* Codebuff Agent Type Definitions
|
||||
*
|
||||
* This file provides TypeScript type definitions for creating custom Codebuff agents.
|
||||
* Import these types in your agent files to get full type safety and IntelliSense.
|
||||
*
|
||||
* Usage in .agents/your-agent.ts:
|
||||
* import { AgentDefinition, ToolName, ModelName } from './types/agent-definition'
|
||||
*
|
||||
* const definition: AgentDefinition = {
|
||||
* // ... your agent configuration with full type safety ...
|
||||
* }
|
||||
*
|
||||
* export default definition
|
||||
*/
|
||||
|
||||
// ============================================================================
|
||||
// Agent Definition and Utility Types
|
||||
// ============================================================================
|
||||
|
||||
export interface AgentDefinition {
|
||||
/** Unique identifier for this agent. Must contain only lowercase letters, numbers, and hyphens, e.g. 'code-reviewer' */
|
||||
id: string
|
||||
|
||||
/** Version string (if not provided, will default to '0.0.1' and be bumped on each publish) */
|
||||
version?: string
|
||||
|
||||
/** Publisher ID for the agent. Must be provided if you want to publish the agent. */
|
||||
publisher?: string
|
||||
|
||||
/** Human-readable name for the agent */
|
||||
displayName: string
|
||||
|
||||
/** AI model to use for this agent. Can be any model in OpenRouter: https://openrouter.ai/models */
|
||||
model: ModelName
|
||||
|
||||
/**
|
||||
* https://openrouter.ai/docs/use-cases/reasoning-tokens
|
||||
* One of `max_tokens` or `effort` is required.
|
||||
* If `exclude` is true, reasoning will be removed from the response. Default is false.
|
||||
*/
|
||||
reasoningOptions?: {
|
||||
enabled?: boolean
|
||||
exclude?: boolean
|
||||
} & (
|
||||
| {
|
||||
max_tokens: number
|
||||
}
|
||||
| {
|
||||
effort: 'high' | 'medium' | 'low' | 'minimal' | 'none'
|
||||
}
|
||||
)
|
||||
|
||||
/**
|
||||
* Provider routing options for OpenRouter.
|
||||
* Controls which providers to use and fallback behavior.
|
||||
* See https://openrouter.ai/docs/features/provider-routing
|
||||
*/
|
||||
providerOptions?: {
|
||||
/**
|
||||
* List of provider slugs to try in order (e.g. ["anthropic", "openai"])
|
||||
*/
|
||||
order?: string[]
|
||||
/**
|
||||
* Whether to allow backup providers when primary is unavailable (default: true)
|
||||
*/
|
||||
allow_fallbacks?: boolean
|
||||
/**
|
||||
* Only use providers that support all parameters in your request (default: false)
|
||||
*/
|
||||
require_parameters?: boolean
|
||||
/**
|
||||
* Control whether to use providers that may store data
|
||||
*/
|
||||
data_collection?: 'allow' | 'deny'
|
||||
/**
|
||||
* List of provider slugs to allow for this request
|
||||
*/
|
||||
only?: string[]
|
||||
/**
|
||||
* List of provider slugs to skip for this request
|
||||
*/
|
||||
ignore?: string[]
|
||||
/**
|
||||
* List of quantization levels to filter by (e.g. ["int4", "int8"])
|
||||
*/
|
||||
quantizations?: Array<
|
||||
| 'int4'
|
||||
| 'int8'
|
||||
| 'fp4'
|
||||
| 'fp6'
|
||||
| 'fp8'
|
||||
| 'fp16'
|
||||
| 'bf16'
|
||||
| 'fp32'
|
||||
| 'unknown'
|
||||
>
|
||||
/**
|
||||
* Sort providers by price, throughput, or latency
|
||||
*/
|
||||
sort?: 'price' | 'throughput' | 'latency'
|
||||
/**
|
||||
* Maximum pricing you want to pay for this request
|
||||
*/
|
||||
max_price?: {
|
||||
prompt?: number | string
|
||||
completion?: number | string
|
||||
image?: number | string
|
||||
audio?: number | string
|
||||
request?: number | string
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Tools and Subagents
|
||||
// ============================================================================
|
||||
|
||||
/** MCP servers by name. Names cannot contain `/`. */
|
||||
mcpServers?: Record<string, MCPConfig>
|
||||
|
||||
/**
|
||||
* Tools this agent can use.
|
||||
*
|
||||
* By default, all tools are available from any specified MCP server. In
|
||||
* order to limit the tools from a specific MCP server, add the tool name(s)
|
||||
* in the format `'mcpServerName/toolName1'`, `'mcpServerName/toolName2'`,
|
||||
* etc.
|
||||
*/
|
||||
toolNames?: (ToolName | (string & {}))[]
|
||||
|
||||
/** Other agents this agent can spawn, like 'codebuff/file-picker@0.0.1'.
|
||||
*
|
||||
* Use the fully qualified agent id from the agent store, including publisher and version: 'codebuff/file-picker@0.0.1'
|
||||
* (publisher and version are required!)
|
||||
*
|
||||
* Or, use the agent id from a local agent file in your .agents directory: 'file-picker'.
|
||||
*/
|
||||
spawnableAgents?: string[]
|
||||
|
||||
// ============================================================================
|
||||
// Input and Output
|
||||
// ============================================================================
|
||||
|
||||
/** The input schema required to spawn the agent. Provide a prompt string and/or a params object or none.
|
||||
* 80% of the time you want just a prompt string with a description:
|
||||
* inputSchema: {
|
||||
* prompt: { type: 'string', description: 'A description of what info would be helpful to the agent' }
|
||||
* }
|
||||
*/
|
||||
inputSchema?: {
|
||||
prompt?: { type: 'string'; description?: string }
|
||||
params?: JsonObjectSchema
|
||||
}
|
||||
|
||||
/** How the agent should output a response to its parent (defaults to 'last_message')
|
||||
*
|
||||
* last_message: The last message from the agent, typically after using tools.
|
||||
*
|
||||
* all_messages: All messages from the agent, including tool calls and results.
|
||||
*
|
||||
* structured_output: Make the agent output a JSON object. Can be used with outputSchema or without if you want freeform json output.
|
||||
*/
|
||||
outputMode?: 'last_message' | 'all_messages' | 'structured_output'
|
||||
|
||||
/** JSON schema for structured output (when outputMode is 'structured_output') */
|
||||
outputSchema?: JsonObjectSchema
|
||||
|
||||
// ============================================================================
|
||||
// Prompts
|
||||
// ============================================================================
|
||||
|
||||
/** Prompt for when and why to spawn this agent. Include the main purpose and use cases.
|
||||
*
|
||||
* This field is key if the agent is intended to be spawned by other agents. */
|
||||
spawnerPrompt?: string
|
||||
|
||||
/** Whether to include conversation history from the parent agent in context.
|
||||
*
|
||||
* Defaults to false.
|
||||
* Use this when the agent needs to know all the previous messages in the conversation.
|
||||
*/
|
||||
includeMessageHistory?: boolean
|
||||
|
||||
/** Whether to inherit the parent agent's system prompt instead of using this agent's own systemPrompt.
|
||||
*
|
||||
* Defaults to false.
|
||||
* Use this when you want to enable prompt caching by preserving the same system prompt prefix.
|
||||
* Cannot be used together with the systemPrompt field.
|
||||
*/
|
||||
inheritParentSystemPrompt?: boolean
|
||||
|
||||
/** Background information for the agent. Fairly optional. Prefer using instructionsPrompt for agent instructions. */
|
||||
systemPrompt?: string
|
||||
|
||||
/** Instructions for the agent.
|
||||
*
|
||||
* IMPORTANT: Updating this prompt is the best way to shape the agent's behavior.
|
||||
* This prompt is inserted after each user input. */
|
||||
instructionsPrompt?: string
|
||||
|
||||
/** Prompt inserted at each agent step.
|
||||
*
|
||||
* Powerful for changing the agent's behavior, but usually not necessary for smart models.
|
||||
* Prefer instructionsPrompt for most instructions. */
|
||||
stepPrompt?: string
|
||||
|
||||
// ============================================================================
|
||||
// Handle Steps
|
||||
// ============================================================================
|
||||
|
||||
/** Programmatically step the agent forward and run tools.
|
||||
*
|
||||
* You can either yield:
|
||||
* - A tool call object with toolName and input properties.
|
||||
* - 'STEP' to run agent's model and generate one assistant message.
|
||||
* - 'STEP_ALL' to run the agent's model until it uses the end_turn tool or stops includes no tool calls in a message.
|
||||
*
|
||||
* Or use 'return' to end the turn.
|
||||
*
|
||||
* Example 1:
|
||||
* function* handleSteps({ agentState, prompt, params, logger }) {
|
||||
* logger.info('Starting file read process')
|
||||
* const { toolResult } = yield {
|
||||
* toolName: 'read_files',
|
||||
* input: { paths: ['file1.txt', 'file2.txt'] }
|
||||
* }
|
||||
* yield 'STEP_ALL'
|
||||
*
|
||||
* // Optionally do a post-processing step here...
|
||||
* logger.info('Files read successfully, setting output')
|
||||
* yield {
|
||||
* toolName: 'set_output',
|
||||
* input: {
|
||||
* output: 'The files were read successfully.',
|
||||
* },
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* Example 2:
|
||||
* handleSteps: function* ({ agentState, prompt, params, logger }) {
|
||||
* while (true) {
|
||||
* logger.debug('Spawning thinker agent')
|
||||
* yield {
|
||||
* toolName: 'spawn_agents',
|
||||
* input: {
|
||||
* agents: [
|
||||
* {
|
||||
* agent_type: 'thinker',
|
||||
* prompt: 'Think deeply about the user request',
|
||||
* },
|
||||
* ],
|
||||
* },
|
||||
* }
|
||||
* const { stepsComplete } = yield 'STEP'
|
||||
* if (stepsComplete) break
|
||||
* }
|
||||
* }
|
||||
*/
|
||||
handleSteps?: (context: AgentStepContext) => Generator<
|
||||
ToolCall | 'STEP' | 'STEP_ALL' | StepText | GenerateN,
|
||||
void,
|
||||
{
|
||||
agentState: AgentState
|
||||
toolResult: ToolResultOutput[] | undefined
|
||||
stepsComplete: boolean
|
||||
nResponses?: string[]
|
||||
}
|
||||
>
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Supporting Types
|
||||
// ============================================================================
|
||||
|
||||
export interface AgentState {
|
||||
agentId: string
|
||||
runId: string
|
||||
parentId: string | undefined
|
||||
|
||||
/** The agent's conversation history: messages from the user and the assistant. */
|
||||
messageHistory: Message[]
|
||||
|
||||
/** The last value set by the set_output tool. This is a plain object or undefined if not set. */
|
||||
output: Record<string, any> | undefined
|
||||
|
||||
/** The system prompt for this agent. */
|
||||
systemPrompt: string
|
||||
|
||||
/** The tool definitions for this agent. */
|
||||
toolDefinitions: Record<
|
||||
string,
|
||||
{ description: string | undefined; inputSchema: {} }
|
||||
>
|
||||
|
||||
/**
|
||||
* The token count from the Anthropic API.
|
||||
* This is updated on every agent step via the /api/v1/token-count endpoint.
|
||||
*/
|
||||
contextTokenCount: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Context provided to handleSteps generator function
|
||||
*/
|
||||
export interface AgentStepContext {
|
||||
agentState: AgentState
|
||||
prompt?: string
|
||||
params?: Record<string, any>
|
||||
logger: Logger
|
||||
}
|
||||
|
||||
export type StepText = { type: 'STEP_TEXT'; text: string }
|
||||
export type GenerateN = { type: 'GENERATE_N'; n: number }
|
||||
|
||||
/**
|
||||
* Tool call object for handleSteps generator
|
||||
*/
|
||||
export type ToolCall<T extends ToolName = ToolName> = {
|
||||
[K in T]: {
|
||||
toolName: K
|
||||
input: GetToolParams<K>
|
||||
includeToolCall?: boolean
|
||||
}
|
||||
}[T]
|
||||
|
||||
// ============================================================================
|
||||
// Available Tools
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* File operation tools
|
||||
*/
|
||||
export type FileEditingTools = 'read_files' | 'write_file' | 'str_replace'
|
||||
|
||||
/**
|
||||
* Code analysis tools
|
||||
*/
|
||||
export type CodeAnalysisTools = 'code_search' | 'find_files' | 'read_files'
|
||||
|
||||
/**
|
||||
* Terminal and system tools
|
||||
*/
|
||||
export type TerminalTools = 'run_terminal_command' | 'code_search'
|
||||
|
||||
/**
|
||||
* Web and browser tools
|
||||
*/
|
||||
export type WebTools = 'web_search' | 'read_docs'
|
||||
|
||||
/**
|
||||
* Agent management tools
|
||||
*/
|
||||
export type AgentTools = 'spawn_agents'
|
||||
|
||||
/**
|
||||
* Output and control tools
|
||||
*/
|
||||
export type OutputTools = 'set_output'
|
||||
|
||||
// ============================================================================
|
||||
// Available Models (see: https://openrouter.ai/models)
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* AI models available for agents. Pick from our selection of recommended models or choose any model in OpenRouter.
|
||||
*
|
||||
* See available models at https://openrouter.ai/models
|
||||
*/
|
||||
export type ModelName =
|
||||
// Recommended Models
|
||||
|
||||
// OpenAI
|
||||
| 'openai/gpt-5.1'
|
||||
| 'openai/gpt-5.1-chat'
|
||||
| 'openai/gpt-5-mini'
|
||||
| 'openai/gpt-5-nano'
|
||||
|
||||
// Anthropic
|
||||
| 'anthropic/claude-sonnet-4.5'
|
||||
| 'anthropic/claude-opus-4.1'
|
||||
|
||||
// Gemini
|
||||
| 'google/gemini-2.5-pro'
|
||||
| 'google/gemini-2.5-flash'
|
||||
| 'google/gemini-2.5-flash-lite'
|
||||
| 'google/gemini-2.5-flash-preview-09-2025'
|
||||
| 'google/gemini-2.5-flash-lite-preview-09-2025'
|
||||
|
||||
// X-AI
|
||||
| 'x-ai/grok-4-07-09'
|
||||
| 'x-ai/grok-4-fast'
|
||||
| 'x-ai/grok-code-fast-1'
|
||||
|
||||
// Qwen
|
||||
| 'qwen/qwen3-max'
|
||||
| 'qwen/qwen3-coder-plus'
|
||||
| 'qwen/qwen3-coder'
|
||||
| 'qwen/qwen3-coder:nitro'
|
||||
| 'qwen/qwen3-coder-flash'
|
||||
| 'qwen/qwen3-235b-a22b-2507'
|
||||
| 'qwen/qwen3-235b-a22b-2507:nitro'
|
||||
| 'qwen/qwen3-235b-a22b-thinking-2507'
|
||||
| 'qwen/qwen3-235b-a22b-thinking-2507:nitro'
|
||||
| 'qwen/qwen3-30b-a3b'
|
||||
| 'qwen/qwen3-30b-a3b:nitro'
|
||||
|
||||
// DeepSeek
|
||||
| 'deepseek/deepseek-chat-v3-0324'
|
||||
| 'deepseek/deepseek-chat-v3-0324:nitro'
|
||||
| 'deepseek/deepseek-r1-0528'
|
||||
| 'deepseek/deepseek-r1-0528:nitro'
|
||||
|
||||
// Other open source models
|
||||
| 'moonshotai/kimi-k2'
|
||||
| 'moonshotai/kimi-k2:nitro'
|
||||
| 'z-ai/glm-4.6'
|
||||
| 'z-ai/glm-4.6:nitro'
|
||||
| (string & {})
|
||||
|
||||
import type { ToolName, GetToolParams } from './tools'
|
||||
import type {
|
||||
Message,
|
||||
ToolResultOutput,
|
||||
JsonObjectSchema,
|
||||
MCPConfig,
|
||||
Logger,
|
||||
} from './util-types'
|
||||
|
||||
export type { ToolName, GetToolParams }
|
||||
@@ -1,316 +0,0 @@
|
||||
/**
|
||||
* Union type of all available tool names
|
||||
*/
|
||||
export type ToolName =
|
||||
| 'add_message'
|
||||
| 'ask_user'
|
||||
| 'code_search'
|
||||
| 'end_turn'
|
||||
| 'find_files'
|
||||
| 'glob'
|
||||
| 'list_directory'
|
||||
| 'lookup_agent_info'
|
||||
| 'read_docs'
|
||||
| 'read_files'
|
||||
| 'read_subtree'
|
||||
| 'run_file_change_hooks'
|
||||
| 'run_terminal_command'
|
||||
| 'set_messages'
|
||||
| 'set_output'
|
||||
| 'spawn_agents'
|
||||
| 'str_replace'
|
||||
| 'suggest_followups'
|
||||
| 'task_completed'
|
||||
| 'think_deeply'
|
||||
| 'web_search'
|
||||
| 'write_file'
|
||||
| 'write_todos'
|
||||
|
||||
/**
|
||||
* Map of tool names to their parameter types
|
||||
*/
|
||||
export interface ToolParamsMap {
|
||||
add_message: AddMessageParams
|
||||
ask_user: AskUserParams
|
||||
code_search: CodeSearchParams
|
||||
end_turn: EndTurnParams
|
||||
find_files: FindFilesParams
|
||||
glob: GlobParams
|
||||
list_directory: ListDirectoryParams
|
||||
lookup_agent_info: LookupAgentInfoParams
|
||||
read_docs: ReadDocsParams
|
||||
read_files: ReadFilesParams
|
||||
read_subtree: ReadSubtreeParams
|
||||
run_file_change_hooks: RunFileChangeHooksParams
|
||||
run_terminal_command: RunTerminalCommandParams
|
||||
set_messages: SetMessagesParams
|
||||
set_output: SetOutputParams
|
||||
spawn_agents: SpawnAgentsParams
|
||||
str_replace: StrReplaceParams
|
||||
suggest_followups: SuggestFollowupsParams
|
||||
task_completed: TaskCompletedParams
|
||||
think_deeply: ThinkDeeplyParams
|
||||
web_search: WebSearchParams
|
||||
write_file: WriteFileParams
|
||||
write_todos: WriteTodosParams
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a new message to the conversation history. To be used for complex requests that can't be solved in a single step, as you may forget what happened!
|
||||
*/
|
||||
export interface AddMessageParams {
|
||||
role: 'user' | 'assistant'
|
||||
content: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Ask the user multiple choice questions and pause execution until they respond.
|
||||
*/
|
||||
export interface AskUserParams {
|
||||
/** List of multiple choice questions to ask the user */
|
||||
questions: {
|
||||
/** The question to ask the user */
|
||||
question: string
|
||||
/** Short label (max 12 chars) displayed as a chip/tag */
|
||||
header?: string
|
||||
/** Array of answer options with label and optional description (minimum 2) */
|
||||
options: {
|
||||
/** The display text for this option */
|
||||
label: string
|
||||
/** Explanation shown when option is focused */
|
||||
description?: string
|
||||
}[]
|
||||
/** If true, allows selecting multiple options (checkbox). If false, single selection only (radio). */
|
||||
multiSelect?: boolean
|
||||
/** Validation rules for "Other" text input */
|
||||
validation?: {
|
||||
/** Maximum length for "Other" text input */
|
||||
maxLength?: number
|
||||
/** Minimum length for "Other" text input */
|
||||
minLength?: number
|
||||
/** Regex pattern for "Other" text input */
|
||||
pattern?: string
|
||||
/** Custom error message when pattern fails */
|
||||
patternError?: string
|
||||
}
|
||||
}[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Search for string patterns in the project's files. This tool uses ripgrep (rg), a fast line-oriented search tool. Use this tool only when read_files is not sufficient to find the files you need.
|
||||
*/
|
||||
export interface CodeSearchParams {
|
||||
/** The pattern to search for. */
|
||||
pattern: string
|
||||
/** Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-g *.ts -g *.js" for TypeScript and JavaScript files only, "-g !*.test.ts" to exclude Typescript test files, "-A 3" for 3 lines after match, "-B 2" for 2 lines before match). */
|
||||
flags?: string
|
||||
/** Optional working directory to search within, relative to the project root. Defaults to searching the entire project. */
|
||||
cwd?: string
|
||||
/** Maximum number of results to return per file. Defaults to 15. There is also a global limit of 250 results across all files. */
|
||||
maxResults?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* End your turn, regardless of any new tool results that might be coming. This will allow the user to type another prompt.
|
||||
*/
|
||||
export interface EndTurnParams {}
|
||||
|
||||
/**
|
||||
* Find several files related to a brief natural language description of the files or the name of a function or class you are looking for.
|
||||
*/
|
||||
export interface FindFilesParams {
|
||||
/** A brief natural language description of the files or the name of a function or class you are looking for. It's also helpful to mention a directory or two to look within. */
|
||||
prompt: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Search for files matching a glob pattern. Returns matching file paths sorted by modification time.
|
||||
*/
|
||||
export interface GlobParams {
|
||||
/** Glob pattern to match files against (e.g., *.js, src/glob/*.ts, glob/test/glob/*.go). */
|
||||
pattern: string
|
||||
/** Optional working directory to search within, relative to project root. If not provided, searches from project root. */
|
||||
cwd?: string
|
||||
}
|
||||
|
||||
/**
|
||||
* List files and directories in the specified path. Returns separate arrays of file names and directory names.
|
||||
*/
|
||||
export interface ListDirectoryParams {
|
||||
/** Directory path to list, relative to the project root. */
|
||||
path: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieve information about an agent by ID
|
||||
*/
|
||||
export interface LookupAgentInfoParams {
|
||||
/** Agent ID (short local or full published format) */
|
||||
agentId: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch up-to-date documentation for libraries and frameworks using Context7 API.
|
||||
*/
|
||||
export interface ReadDocsParams {
|
||||
/** The library or framework name (e.g., "Next.js", "MongoDB", "React"). Use the official name as it appears in documentation if possible. Only public libraries available in Context7's database are supported, so small or private libraries may not be available. */
|
||||
libraryTitle: string
|
||||
/** Specific topic to focus on (e.g., "routing", "hooks", "authentication") */
|
||||
topic: string
|
||||
/** Optional maximum number of tokens to return. Defaults to 20000. Values less than 10000 are automatically increased to 10000. */
|
||||
max_tokens?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the multiple files from disk and return their contents. Use this tool to read as many files as would be helpful to answer the user's request.
|
||||
*/
|
||||
export interface ReadFilesParams {
|
||||
/** List of file paths to read. */
|
||||
paths: string[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Read one or more directory subtrees (as a blob including subdirectories, file names, and parsed variables within each source file) or return parsed variable names for files. If no paths are provided, returns the entire project tree.
|
||||
*/
|
||||
export interface ReadSubtreeParams {
|
||||
/** List of paths to directories or files. Relative to the project root. If omitted, the entire project tree is used. */
|
||||
paths?: string[]
|
||||
/** Maximum token budget for the subtree blob; the tree will be truncated to fit within this budget by first dropping file variables and then removing the most-nested files and directories. */
|
||||
maxTokens?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Parameters for run_file_change_hooks tool
|
||||
*/
|
||||
export interface RunFileChangeHooksParams {
|
||||
/** List of file paths that were changed and should trigger file change hooks */
|
||||
files: string[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute a CLI command from the **project root** (different from the user's cwd).
|
||||
*/
|
||||
export interface RunTerminalCommandParams {
|
||||
/** CLI command valid for user's OS. */
|
||||
command: string
|
||||
/** Either SYNC (waits, returns output) or BACKGROUND (runs in background). Default SYNC */
|
||||
process_type?: 'SYNC' | 'BACKGROUND'
|
||||
/** The working directory to run the command in. Default is the project root. */
|
||||
cwd?: string
|
||||
/** Set to -1 for no timeout. Does not apply for BACKGROUND commands. Default 30 */
|
||||
timeout_seconds?: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the conversation history to the provided messages.
|
||||
*/
|
||||
export interface SetMessagesParams {
|
||||
messages: any
|
||||
}
|
||||
|
||||
/**
|
||||
* JSON object to set as the agent output. This completely replaces any previous output. If the agent was spawned, this value will be passed back to its parent. If the agent has an outputSchema defined, the output will be validated against it.
|
||||
*/
|
||||
export interface SetOutputParams {}
|
||||
|
||||
/**
|
||||
* Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead.
|
||||
*/
|
||||
export interface SpawnAgentsParams {
|
||||
agents: {
|
||||
/** Agent to spawn */
|
||||
agent_type: string
|
||||
/** Prompt to send to the agent */
|
||||
prompt?: string
|
||||
/** Parameters object for the agent (if any) */
|
||||
params?: Record<string, any>
|
||||
}[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Replace strings in a file with new strings.
|
||||
*/
|
||||
export interface StrReplaceParams {
|
||||
/** The path to the file to edit. */
|
||||
path: string
|
||||
/** Array of replacements to make. */
|
||||
replacements: {
|
||||
/** The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation. */
|
||||
old: string
|
||||
/** The string to replace the corresponding old string with. Can be empty to delete. */
|
||||
new: string
|
||||
/** Whether to allow multiple replacements of old string. */
|
||||
allowMultiple?: boolean
|
||||
}[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Suggest clickable followup prompts to the user.
|
||||
*/
|
||||
export interface SuggestFollowupsParams {
|
||||
/** List of suggested followup prompts the user can click to send */
|
||||
followups: {
|
||||
/** The full prompt text to send as a user message when clicked */
|
||||
prompt: string
|
||||
/** Short display label for the card (defaults to truncated prompt if not provided) */
|
||||
label?: string
|
||||
}[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Signal that the task is complete. Use this tool when:
|
||||
- The user's request is completely fulfilled
|
||||
- You need clarification from the user before continuing
|
||||
- You are stuck or need help from the user to continue
|
||||
|
||||
This tool explicitly marks the end of your work on the current task.
|
||||
*/
|
||||
export interface TaskCompletedParams {}
|
||||
|
||||
/**
|
||||
* Deeply consider complex tasks by brainstorming approaches and tradeoffs step-by-step.
|
||||
*/
|
||||
export interface ThinkDeeplyParams {
|
||||
/** Detailed step-by-step analysis. Initially keep each step concise (max ~5-7 words per step). */
|
||||
thought: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Search the web for current information using Linkup API.
|
||||
*/
|
||||
export interface WebSearchParams {
|
||||
/** The search query to find relevant web content */
|
||||
query: string
|
||||
/** Search depth - 'standard' for quick results, 'deep' for more comprehensive search. Default is 'standard'. */
|
||||
depth?: 'standard' | 'deep'
|
||||
}
|
||||
|
||||
/**
|
||||
* Create or edit a file with the given content.
|
||||
*/
|
||||
export interface WriteFileParams {
|
||||
/** Path to the file relative to the **project root** */
|
||||
path: string
|
||||
/** What the change is intended to do in only one sentence. */
|
||||
instructions: string
|
||||
/** Edit snippet to apply to the file. */
|
||||
content: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Write a todo list to track tasks for multi-step implementations. Use this frequently to maintain an updated step-by-step plan.
|
||||
*/
|
||||
export interface WriteTodosParams {
|
||||
/** List of todos with their completion status. Add ALL of the applicable tasks to the list, so you don't forget to do anything. Try to order the todos the same way you will complete them. Do not mark todos as completed if you have not completed them yet! */
|
||||
todos: {
|
||||
/** Description of the task */
|
||||
task: string
|
||||
/** Whether the task is completed */
|
||||
completed: boolean
|
||||
}[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Get parameters type for a specific tool
|
||||
*/
|
||||
export type GetToolParams<T extends ToolName> = ToolParamsMap[T]
|
||||
@@ -1,175 +0,0 @@
|
||||
// ===== JSON Types =====
|
||||
export type JSONValue =
|
||||
| null
|
||||
| string
|
||||
| number
|
||||
| boolean
|
||||
| JSONObject
|
||||
| JSONArray
|
||||
|
||||
export type JSONObject = { [key: string]: JSONValue }
|
||||
|
||||
export type JSONArray = JSONValue[]
|
||||
|
||||
/**
|
||||
* JSON Schema definition (for prompt schema or output schema)
|
||||
*/
|
||||
export type JsonSchema = {
|
||||
type?:
|
||||
| 'object'
|
||||
| 'array'
|
||||
| 'string'
|
||||
| 'number'
|
||||
| 'boolean'
|
||||
| 'null'
|
||||
| 'integer'
|
||||
description?: string
|
||||
properties?: Record<string, JsonSchema | boolean>
|
||||
required?: string[]
|
||||
enum?: Array<string | number | boolean | null>
|
||||
[k: string]: unknown
|
||||
}
|
||||
export type JsonObjectSchema = JsonSchema & { type: 'object' }
|
||||
|
||||
// ===== Data Content Types =====
|
||||
export type DataContent = string | Uint8Array | ArrayBuffer | Buffer
|
||||
|
||||
// ===== Provider Metadata Types =====
|
||||
export type ProviderMetadata = Record<string, Record<string, JSONValue>>
|
||||
|
||||
// ===== Content Part Types =====
|
||||
export type TextPart = {
|
||||
type: 'text'
|
||||
text: string
|
||||
providerOptions?: ProviderMetadata
|
||||
}
|
||||
|
||||
export type ImagePart = {
|
||||
type: 'image'
|
||||
image: DataContent
|
||||
mediaType?: string
|
||||
providerOptions?: ProviderMetadata
|
||||
}
|
||||
|
||||
export type FilePart = {
|
||||
type: 'file'
|
||||
data: DataContent
|
||||
filename?: string
|
||||
mediaType: string
|
||||
providerOptions?: ProviderMetadata
|
||||
}
|
||||
|
||||
export type ReasoningPart = {
|
||||
type: 'reasoning'
|
||||
text: string
|
||||
providerOptions?: ProviderMetadata
|
||||
}
|
||||
|
||||
export type ToolCallPart = {
|
||||
type: 'tool-call'
|
||||
toolCallId: string
|
||||
toolName: string
|
||||
input: Record<string, unknown>
|
||||
providerOptions?: ProviderMetadata
|
||||
providerExecuted?: boolean
|
||||
}
|
||||
|
||||
export type ToolResultOutput =
|
||||
| {
|
||||
type: 'json'
|
||||
value: JSONValue
|
||||
}
|
||||
| {
|
||||
type: 'media'
|
||||
data: string
|
||||
mediaType: string
|
||||
}
|
||||
|
||||
// ===== Message Types =====
|
||||
export type AuxiliaryMessageData = {
|
||||
providerOptions?: ProviderMetadata
|
||||
tags?: string[]
|
||||
|
||||
/** @deprecated Use tags instead. */
|
||||
timeToLive?: 'agentStep' | 'userPrompt'
|
||||
/** @deprecated Use tags instead. */
|
||||
keepDuringTruncation?: boolean
|
||||
/** @deprecated Use tags instead. */
|
||||
keepLastTags?: string[]
|
||||
}
|
||||
|
||||
export type SystemMessage = {
|
||||
role: 'system'
|
||||
content: TextPart[]
|
||||
} & AuxiliaryMessageData
|
||||
|
||||
export type UserMessage = {
|
||||
role: 'user'
|
||||
content: (TextPart | ImagePart | FilePart)[]
|
||||
} & AuxiliaryMessageData
|
||||
|
||||
export type AssistantMessage = {
|
||||
role: 'assistant'
|
||||
content: (TextPart | ReasoningPart | ToolCallPart)[]
|
||||
} & AuxiliaryMessageData
|
||||
|
||||
export type ToolMessage = {
|
||||
role: 'tool'
|
||||
toolCallId: string
|
||||
toolName: string
|
||||
content: ToolResultOutput[]
|
||||
} & AuxiliaryMessageData
|
||||
|
||||
export type Message =
|
||||
| SystemMessage
|
||||
| UserMessage
|
||||
| AssistantMessage
|
||||
| ToolMessage
|
||||
|
||||
// ===== MCP Server Types =====
|
||||
|
||||
/**
|
||||
* MCP server configuration for stdio-based servers.
|
||||
*
|
||||
* Environment variables in `env` can be:
|
||||
* - A plain string value (hardcoded, e.g., `'production'`)
|
||||
* - A `$VAR_NAME` reference to read from local environment (e.g., `'$NOTION_TOKEN'`)
|
||||
*
|
||||
* The `$VAR_NAME` syntax reads from `process.env.VAR_NAME` at agent load time.
|
||||
* This keeps secrets out of your agent definitions - store them in `.env.local` instead.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* env: {
|
||||
* // Read NOTION_TOKEN from local .env file
|
||||
* NOTION_TOKEN: '$NOTION_TOKEN',
|
||||
* // Read MY_API_KEY from local env, pass as API_KEY to MCP server
|
||||
* API_KEY: '$MY_API_KEY',
|
||||
* // Hardcoded value (non-secret)
|
||||
* NODE_ENV: 'production',
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export type MCPConfig =
|
||||
| {
|
||||
type?: 'stdio'
|
||||
command: string
|
||||
args?: string[]
|
||||
env?: Record<string, string>
|
||||
}
|
||||
| {
|
||||
type?: 'http' | 'sse'
|
||||
url: string
|
||||
params?: Record<string, string>
|
||||
headers?: Record<string, string>
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Logger Interface
|
||||
// ============================================================================
|
||||
export interface Logger {
|
||||
debug: (data: any, msg?: string) => void
|
||||
info: (data: any, msg?: string) => void
|
||||
warn: (data: any, msg?: string) => void
|
||||
error: (data: any, msg?: string) => void
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
{"mcpServers":{"MCP_DOCKER":{"command":"docker","args":["mcp","gateway","run"]}}}
|
||||
+3
-4
@@ -36,7 +36,6 @@ yarn-error.log*
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
.roo/
|
||||
|
||||
# cursor
|
||||
.cursor
|
||||
# MCP konfiguráció (API kulcsokat tartalmaz — soha ne commitolj!)
|
||||
.mcp.json
|
||||
mcp.json
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"plane": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@makeplane/plane-mcp-server"],
|
||||
"env": {
|
||||
"PLANE_API_KEY": "plane_api_YOUR_TOKEN_HERE",
|
||||
"PLANE_API_HOST_URL": "https://pm.llmdev.mozdit.hu/",
|
||||
"PLANE_WORKSPACE_SLUG": "developments"
|
||||
},
|
||||
"disabled": false,
|
||||
"autoApprove": [
|
||||
"create_issue",
|
||||
"update_issue",
|
||||
"get_projects",
|
||||
"list_project_issues",
|
||||
"list_states",
|
||||
"list_labels",
|
||||
"get_issue_using_readable_identifier",
|
||||
"get_issue_comments",
|
||||
"add_issue_comment"
|
||||
]
|
||||
},
|
||||
"MCP_DOCKER": {
|
||||
"command": "docker",
|
||||
"args": ["mcp", "gateway", "run"],
|
||||
"type": "stdio"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,41 +0,0 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"@playwright/mcp@latest"
|
||||
],
|
||||
"env": {}
|
||||
},
|
||||
"git": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-server-git"
|
||||
],
|
||||
"env": {}
|
||||
},
|
||||
"Zapier": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"mcp-remote",
|
||||
"https://mcp.zapier.com/api/mcp/s/MzVkMzJmMDEtNzkwNC00MzAxLTgyNDgtZDQ1MTU1MThlYmVlOjJhM2I3ZWM3LTZjNTQtNGEyNy1hY2YyLTNjZjE5MDNmZTkyMw==/mcp",
|
||||
"--transport",
|
||||
"http-only"
|
||||
]
|
||||
},
|
||||
"linear": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://mcp.linear.app/sse"
|
||||
],
|
||||
"alwaysAllow": [
|
||||
"list_issues",
|
||||
"get_issue",
|
||||
"update_issue",
|
||||
"create_issue"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,177 +1,102 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
> **[AI AGENT — OLVASD EL ELŐSZÖR]**
|
||||
> Ez a fájl egy gyors referencia. A teljes szabályrendszer és workflow-ok a `.agent/` mappában találhatók.
|
||||
> **Kötelező elolvasni**: `.agent/AGENTS.md` → `.agent/steering/development-rules.md` → `.agent/steering/architecture.md`
|
||||
|
||||
## Project Overview
|
||||
---
|
||||
|
||||
This is the mozdIT Bt. website development project - a Next.js 14 application for a Hungarian IT services company. The codebase includes both frontend and backend functionality for hosting, email services, and DNS administration services.
|
||||
## Projekt azonosítás
|
||||
|
||||
## Project Structure
|
||||
- **Projekt**: mozdIT Bt. weboldal (websitedev)
|
||||
- **Plane workspace**: `developments` — `pm.llmdev.mozdit.hu`
|
||||
- **Stack**: Next.js 15, React 19, TypeScript, Tailwind CSS 4, MongoDB, Winston
|
||||
- **Fő könyvtár**: `proto/` — **minden parancsot innen futtatunk**
|
||||
|
||||
---
|
||||
|
||||
## Gyors referencia — Alapszabályok
|
||||
|
||||
1. **Szöveg sosem kerülhet közvetlenül komponensbe** → `proto/src/content/pages/*.json`
|
||||
2. **Feladatok**: `TODO.md` (Linear tükörképe), szinkron: `node linear-sync.js`
|
||||
3. **Tesztek**: minden feature-höz kötelező; commit előtt `npm test` zöld
|
||||
4. **Commit**: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`)
|
||||
5. **Fájlméret**: soft limit 300 sor, hard limit 400 sor
|
||||
6. **Language**: kód+commit = English, kommunikáció+docs = Magyar
|
||||
|
||||
---
|
||||
|
||||
## Kötelező parancsok (`proto/` mappából)
|
||||
|
||||
```bash
|
||||
npm run dev # fejlesztői szerver (Turbopack)
|
||||
npm run build # produkciós build
|
||||
npm run lint # ESLint ellenőrzés
|
||||
npm test # unit tesztek
|
||||
npm run test:coverage # lefedettség riport
|
||||
npm run test:all # teljes test suite
|
||||
node plane-sync.js --list # Plane projektek listázása
|
||||
node plane-sync.js # Plane szinkronizáció
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Projekt struktúra
|
||||
|
||||
```
|
||||
websitedev/
|
||||
├── proto/ # Main Next.js application
|
||||
│ ├── src/
|
||||
│ │ ├── app/ # Next.js App Router (pages and API routes)
|
||||
│ │ ├── components/ # React components (Header, Footer, ThemeProvider)
|
||||
│ │ ├── content/ # JSON content management system
|
||||
│ │ │ ├── types.ts # Content TypeScript definitions
|
||||
│ │ │ ├── index.ts # Content loader utility
|
||||
│ │ │ ├── common.json # Shared texts (buttons, labels)
|
||||
│ │ │ └── pages/ # Page-specific content JSONs
|
||||
│ │ ├── lib/ # Utility libraries (MongoDB, Logger, Site Config)
|
||||
│ │ ├── config/ # Static site configuration
|
||||
│ │ └── types/ # TypeScript type definitions
|
||||
│ ├── public/ # Static assets
|
||||
│ └── package.json
|
||||
├── docs/ # Project documentation (Hungarian)
|
||||
├── TODO.md # Project task tracking (Hungarian)
|
||||
└── linear-sync.js # Linear API synchronization script
|
||||
├── proto/ # Fő Next.js alkalmazás
|
||||
│ └── src/
|
||||
│ ├── app/ # App Router: oldalak és API route-ok
|
||||
│ ├── components/ # React komponensek (PascalCase.tsx)
|
||||
│ ├── content/ # JSON tartalom-kezelő rendszer
|
||||
│ │ ├── common.json # Közös szövegek
|
||||
│ │ └── pages/ # Oldal-specifikus JSONok
|
||||
│ ├── lib/ # MongoDB, Logger, Site Config
|
||||
│ ├── config/ # Statikus site konfiguráció
|
||||
│ └── types/ # TypeScript típusok
|
||||
├── docs/ # Projekt dokumentáció (Magyar)
|
||||
├── .agent/ # AI szabályrendszer ← OLVASD EL
|
||||
│ ├── AGENTS.md # Elsődleges szabályok
|
||||
│ ├── steering/ # Auto-betöltődő irányelvek
|
||||
│ ├── workflows/ # /new-feature, /fix-bug, /review, /deploy
|
||||
│ └── references/ # Accessibility checklist
|
||||
├── TODO.md # Feladatlista (Plane szinkron)
|
||||
└── plane-sync.js # Plane szinkronizáló script
|
||||
```
|
||||
|
||||
## Key Architecture
|
||||
---
|
||||
|
||||
- **Framework**: Next.js 14 with App Router and TypeScript
|
||||
- **UI**: Tailwind CSS 4 with custom fonts (Geist Sans/Mono)
|
||||
- **Design System**: CSS Variables, Dark Mode (ThemeProvider), Animations
|
||||
- **Content Management**: JSON-based structured content in `src/content/`
|
||||
- **Database**: MongoDB with Mongoose ODM
|
||||
- **Logging**: Winston with Loki integration
|
||||
- **Testing**: Jest with React Testing Library
|
||||
- **Deployment**: Dokploy (staging and production)
|
||||
- **Project Management**: Linear (primary), TODO.md (local sync)
|
||||
## Környezeti változók
|
||||
|
||||
## Essential Commands
|
||||
Szükséges változók (`.env` és `proto/.env.local`):
|
||||
- `MONGODB_URI` — MongoDB connection string
|
||||
- `MONGODB_DB` — Adatbázis neve (default: `mozdit`)
|
||||
- `NEXT_PUBLIC_SITE_URL` — Publikus site URL
|
||||
- `NEXT_PUBLIC_WEBMAIL_URL` — Webmail service URL
|
||||
- `NEXT_PUBLIC_CONTACT_EMAIL` — Kapcsolati email cím
|
||||
- `LINEAR_API_KEY` — Linear szinkronizációhoz
|
||||
|
||||
All development commands must be run from the `proto/` directory:
|
||||
---
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
cd proto && npm run dev
|
||||
## API struktúra
|
||||
|
||||
# Production build
|
||||
cd proto && npm run build
|
||||
- `GET /api/health` — Rendszer állapot + MongoDB kapcsolat ellenőrzés
|
||||
- Minden endpoint egységes válasz formátumban: `{ success, data, error }`
|
||||
- Rate limiting érzékeny endpoint-okon (pl. `/api/contact`)
|
||||
|
||||
# Start production server
|
||||
cd proto && npm start
|
||||
---
|
||||
|
||||
# Linting
|
||||
cd proto && npm run lint
|
||||
## Teljes szabályrendszer
|
||||
|
||||
# Testing
|
||||
cd proto && npm test
|
||||
cd proto && npm test:watch
|
||||
cd proto && npm test:coverage
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
- `proto/package.json` - Dependencies and scripts
|
||||
- `proto/tsconfig.json` - TypeScript configuration with path mapping (`@/*` → `./src/*`)
|
||||
- `proto/eslint.config.mjs` - ESLint configuration extending Next.js rules
|
||||
- `proto/next.config.ts` - Next.js configuration (currently minimal)
|
||||
- `proto/jest.config.js` - Jest testing configuration
|
||||
- `.env` - Environment variables (root level)
|
||||
- `proto/.env.local` - Local environment overrides
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Required environment variables (check `.env` and `proto/.env.local`):
|
||||
- `MONGODB_URI` - MongoDB connection string
|
||||
- `MONGODB_DB` - Database name (defaults to 'mozdit')
|
||||
- `NEXT_PUBLIC_SITE_URL` - Public site URL
|
||||
- `NEXT_PUBLIC_WEBMAIL_URL` - Webmail service URL
|
||||
- `NEXT_PUBLIC_CONTACT_EMAIL` - Contact email address
|
||||
- `LINEAR_API_KEY` - For Linear synchronization
|
||||
|
||||
## Site Configuration
|
||||
|
||||
The site uses a centralized configuration system:
|
||||
- `src/config/site.ts` - Main site configuration (company info, navigation, services)
|
||||
- `src/types/site.ts` - TypeScript interfaces for configuration
|
||||
- `src/lib/site-config.ts` - Runtime configuration utilities
|
||||
|
||||
## Content Management System
|
||||
|
||||
All page text content is managed through JSON files for easy modification:
|
||||
|
||||
```
|
||||
src/content/
|
||||
├── types.ts # TypeScript definitions for content
|
||||
├── index.ts # Content loader with getPageContent() helper
|
||||
├── common.json # Shared texts (buttons, labels, validation)
|
||||
└── pages/
|
||||
├── home.json # Homepage CTA, feature labels
|
||||
├── about.json # About page (hero, story, mission, team)
|
||||
├── services.json # Services details, support info
|
||||
└── contact.json # Form labels, FAQ, contact info
|
||||
```
|
||||
|
||||
**Usage in components:**
|
||||
```typescript
|
||||
import { content, getPageContent } from '@/content'
|
||||
|
||||
const { about: pageContent } = content.pages
|
||||
// or
|
||||
const servicesContent = getPageContent('services')
|
||||
```
|
||||
|
||||
## Design System
|
||||
|
||||
The project includes a comprehensive design system:
|
||||
|
||||
- **CSS Variables**: Defined in `globals.css` for colors, shadows, transitions
|
||||
- **Dark Mode**: ThemeProvider component with system preference + manual toggle
|
||||
- **Animations**: fadeIn, float, pulse, hover effects (lift, scale, glow)
|
||||
- **Utility Classes**: `.card`, `.btn`, `.icon-container`, etc.
|
||||
|
||||
## Database Integration
|
||||
|
||||
MongoDB integration is handled through:
|
||||
- `src/lib/mongodb.ts` - Connection management with pooling
|
||||
- Connection health checks available via `/api/health`
|
||||
- Development mode uses global connection caching
|
||||
- Production mode creates fresh connections
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Unit tests for all components and utilities
|
||||
- API endpoint tests for health checks
|
||||
- Test files follow `.test.ts`/`.test.tsx` naming convention
|
||||
- Jest configuration includes jsdom environment for React components
|
||||
- Testing utilities include @testing-library/react and @testing-library/jest-dom
|
||||
|
||||
## Project Management Integration
|
||||
|
||||
The project uses a dual-tracking system:
|
||||
- **Primary**: Linear tickets (ZEE-* series)
|
||||
- **Secondary**: TODO.md for local development tracking
|
||||
|
||||
Use `linear-sync.js` to synchronize between the two systems:
|
||||
```bash
|
||||
node linear-sync.js --dry-run --verbose # Test mode
|
||||
node linear-sync.js # Live sync
|
||||
```
|
||||
|
||||
## Language and Content
|
||||
|
||||
- **Primary language**: Hungarian (site content, documentation)
|
||||
- **Code**: English (variable names, comments, technical terms)
|
||||
- **Target audience**: Hungarian businesses
|
||||
- Site content focuses on web hosting, email services, and DNS administration
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Check Linear for current sprint tasks
|
||||
2. Update TODO.md for local tracking
|
||||
3. Run tests before making changes (`npm test`)
|
||||
4. Use development server with Turbopack for fast iteration
|
||||
5. Run linting before committing (`npm run lint`)
|
||||
6. Sync with Linear using the sync script
|
||||
7. Deploy via Dokploy when ready
|
||||
|
||||
## API Structure
|
||||
|
||||
- `/api/health` - System health check endpoint with MongoDB status
|
||||
- Future API endpoints will follow REST conventions
|
||||
- API routes include comprehensive error handling and logging
|
||||
| Dokumentum | Tartalom |
|
||||
| --- | --- |
|
||||
| `.agent/AGENTS.md` | Összes alapelv, Git konvenciók, mikor kérdezz |
|
||||
| `.agent/steering/development-rules.md` | Kódolási szabályok, bugfix módszertan, intent capture |
|
||||
| `.agent/steering/architecture.md` | Rétegek, adatfolyam, design system szabályok |
|
||||
| `.agent/steering/testing.md` | Tesztelési stratégia, coverage elvárások |
|
||||
| `.agent/workflows/new-feature.md` | Új funkció fejlesztési lépései |
|
||||
| `.agent/workflows/fix-bug.md` | Hibajavítás lépései (TDD) |
|
||||
| `.agent/workflows/review.md` | Code review checklist |
|
||||
| `.agent/workflows/deploy.md` | Deployment folyamat |
|
||||
| `.agent/references/accessibility-checklist.md` | WCAG 2.1 AA ellenőrzőlista |
|
||||
@@ -1,130 +1,90 @@
|
||||
# mozdIT Weboldal - Fejlesztési TODO Lista
|
||||
|
||||
## Projekt Áttekintés
|
||||
Next.js 14 alapú weboldal a mozdIT Bt. számára, Dokploy-on hostolva.
|
||||
Next.js 15 alapú weboldal a mozdIT Bt. számára, Dokploy-on hostolva.
|
||||
|
||||
## ⚠️ Projekt Management
|
||||
**Elsődleges forrás**: Linear (ZEE-28, ZEE-29, ZEE-30, stb.)
|
||||
**Lokális másolat**: Ez a fájl csak referencia, a Linear az authoritative source
|
||||
**Elsődleges forrás**: Plane — `MITHOME` projekt (`pm.llmdev.mozdit.hu`, workspace: `developments`)
|
||||
**Lokális másolat**: Ez a fájl csak referencia, a Plane az authoritative source
|
||||
|
||||
## ✅ Befejezett (Linear szerint)
|
||||
| Linear Ticket | Feladat | Státusz |
|
||||
|---------------|---------|---------|
|
||||
| ZEE-28 | Repo & Next.js bootstrap - befejezett, dev szerver fut localhost:3001-n | ✅ |
|
||||
| ZEE-30 | Kezdőlap (Hero + USP + Webmail CTA) | ✅ |
|
||||
| ZEE-31 | Rólunk oldal | ✅ |
|
||||
| ZEE-32 | Szolgáltatások oldal | ✅ |
|
||||
| ZEE-33 | Kapcsolat űrlap + API stub | ✅ |
|
||||
| ZEE-34 | /api/health endpoint | ✅ |
|
||||
| ZEE-35 | Dockerfile + Docker Compose fejlesztői környezet | ✅ |
|
||||
| ZEE-29 | Tailwind + alap layout (design system, dark mode, animációk) | ✅ |
|
||||
| - | JSON alapú content management rendszer (struktúrált szövegkezelés) | ✅ |
|
||||
| - | Unit teszt infrastruktúra beállítása (Jest + React Testing Library) | ✅ |
|
||||
| - | API endpoint tesztek írása (/api/health) | ✅ |
|
||||
| - | Component tesztek írása (Header, Footer) | ✅ |
|
||||
| - | Teszt hibák javítása (Jest setup, duplicate elements, type casting) | ✅ |
|
||||
| - | Mobil navigáció JavaScript funkcionalitás | ✅ |
|
||||
| - | Contact API endpoint (/api/contact) - rate limiting, spam detection, validáció | ✅ |
|
||||
| - | Docker fejlesztői környezet (Next.js + MongoDB + Mongo Express + Loki + Grafana) | ✅ |
|
||||
| - | MongoDB inicializálás és site_config beállítás | ✅ |
|
||||
---
|
||||
|
||||
## 🔄 Folyamatban (Linear szerint)
|
||||
| Linear Ticket | Feladat | Státusz |
|
||||
|---------------|---------|---------|
|
||||
| - | ZEE-155 | - |
|
||||
## ✅ Befejezett
|
||||
|
||||
## 📋 Tervezett (Backlog)
|
||||
| Linear Ticket | Feladat | Státusz |
|
||||
|---------------|---------|---------|
|
||||
| Plane | Feladat | Státusz |
|
||||
|-------|---------|---------|
|
||||
| MITHOME-1 | Repo & Next.js bootstrap — dev szerver | ✅ |
|
||||
| MITHOME-2 | Kezdőlap (Hero + USP + Webmail CTA) | ✅ |
|
||||
| MITHOME-3 | Rólunk oldal | ✅ |
|
||||
| MITHOME-4 | Szolgáltatások oldal | ✅ |
|
||||
| MITHOME-5 | Kapcsolat űrlap + API route | ✅ |
|
||||
| MITHOME-6 | /api/health endpoint | ✅ |
|
||||
| MITHOME-7 | Dockerfile + Docker Compose fejlesztői környezet | ✅ |
|
||||
| MITHOME-8 | Tailwind + design system, dark mode, animációk | ✅ |
|
||||
| MITHOME-9 | JSON alapú content management rendszer | ✅ |
|
||||
| MITHOME-10 | Unit teszt infrastruktúra (Jest + React Testing Library) | ✅ |
|
||||
| MITHOME-11 | Contact API — rate limiting, spam detection, validáció | ✅ |
|
||||
| MITHOME-12 | Docker stack — Next.js + MongoDB + Loki + Grafana | ✅ |
|
||||
|
||||
| ZEE-36 | CI (lint, unit) + Staging deploy trigger | 📋 |
|
||||
| ZEE-37 | Playwright smoke E2E + Lighthouse CI | 📋 |
|
||||
| ZEE-38 | Prod app + domain + HTTPS | 📋 |
|
||||
| ZEE-39 | Site config migrálás MongoDB-ba | 📋 |
|
||||
| ZEE-40 | Winston logger + Loki integráció | 📋 |
|
||||
| ZEE-154 | Adatvédelmi tájékoztató oldal (/adatvedelem) - GDPR compliance | 📋 |
|
||||
| - | ZEE-156 | 📋 |
|
||||
| - | ZEE-157 | 📋 |
|
||||
---
|
||||
|
||||
## 📋 Követelmény Nyilvántartás (REQ Prefix)
|
||||
| Linear Ticket | Követelmény | Kategória | Státusz |
|
||||
|---------------|-------------|-----------|---------|
|
||||
| ZEE-50 | REQ-001: Kezdőlap Funkcionalitás | Funkcionális | ✅ |
|
||||
| ZEE-51 | REQ-004: Kapcsolat Űrlap | Funkcionális | ✅ |
|
||||
| ZEE-52 | REQ-101: Responsive Design | Nem-funkcionális | ✅ |
|
||||
| ZEE-53 | REQ-102: Accessibility (A11y) | Nem-funkcionális | 🔄 |
|
||||
| ZEE-54 | REQ-401: Lighthouse Score ≥ 90 | Teljesítmény | 🔄 |
|
||||
| ZEE-41 | Logging middleware megvalósítása | 📋 |
|
||||
| ZEE-42 | Grafana dashboard konfiguráció | 📋 |
|
||||
| ZEE-43 | SEO optimalizálás | 📋 |
|
||||
| ZEE-44 | Performance optimalizálás | 📋 |
|
||||
| ZEE-45 | Reszponzív design finomítása | 📋 |
|
||||
## 🔄 Folyamatban
|
||||
|
||||
## 🥒 Test Reporting Rendszer (Gherkin Format)
|
||||
| Funkció | Státusz | Leírás |
|
||||
|---------|---------|---------|
|
||||
| Gherkin generálás | ✅ | Automatikus TC-XXX prefix felismerés |
|
||||
| Funkcionális területek elemzése | ✅ | 8 kategória szerinti csoportosítás |
|
||||
| Coverage dashboard | ✅ | Területenkénti lemaradás elemzés |
|
||||
| TC issue frissítés | ✅ | Linear issues Gherkin formátummal |
|
||||
| Automatizált reporting | ✅ | GitHub Actions integráció |
|
||||
| Plane | Feladat | Státusz |
|
||||
|-------|---------|---------|
|
||||
| — | — | — |
|
||||
|
||||
### 🎯 Funkcionális Területek
|
||||
- **🏠 Weboldal Funkcionalitás**: Kezdőlap, navigáció, oldalak
|
||||
- **📝 Kapcsolat Űrlap**: Validáció, spam védelem, rate limiting
|
||||
- **🎨 Design és UX**: Responsive, accessibility, performance
|
||||
- **🔒 Biztonság**: Input validáció, rate limiting, HTTPS
|
||||
- **⚡ Teljesítmény**: Lighthouse, optimalizálás, caching
|
||||
- **🛠️ Technikai Stack**: Next.js, MongoDB, Docker, CI/CD
|
||||
---
|
||||
|
||||
### 📊 Jelenlegi Test Coverage
|
||||
- **Összes teszt**: 56
|
||||
- **TC-XXX prefix**: 1 (TC-001)
|
||||
- **Funkcionális területek**: 1 (Kapcsolat Űrlap)
|
||||
- **Sikeres tesztek**: 100%
|
||||
- **Lemaradás**: Nincs
|
||||
| ZEE-46 | Analytics integráció | 📋 |
|
||||
## 📋 Backlog
|
||||
|
||||
| Plane | Feladat | Státusz |
|
||||
|-------|---------|---------|
|
||||
| MITHOME-13 | CI pipeline — lint + unit tesztek + staging deploy trigger | 📋 |
|
||||
| MITHOME-14 | Playwright E2E smoke tesztek + Lighthouse CI | 📋 |
|
||||
| MITHOME-15 | Prod app + domain konfiguráció + HTTPS | 📋 |
|
||||
| MITHOME-16 | Site config migrálás MongoDB-ba | 📋 |
|
||||
| MITHOME-17 | Winston logger + Loki integráció | 📋 |
|
||||
| MITHOME-18 | Adatvédelmi tájékoztató oldal (/adatvedelem) — GDPR | 📋 |
|
||||
| MITHOME-19 | Accessibility (A11y) — WCAG 2.1 AA megfelelőség | 📋 |
|
||||
| MITHOME-20 | Lighthouse score ≥ 90 minden kategóriában | 📋 |
|
||||
| MITHOME-21 | Logging middleware megvalósítása | 📋 |
|
||||
| MITHOME-22 | Grafana dashboard konfiguráció | 📋 |
|
||||
| MITHOME-23 | SEO optimalizálás | 📋 |
|
||||
| MITHOME-24 | Performance optimalizálás | 📋 |
|
||||
| MITHOME-25 | Reszponzív design finomítása | 📋 |
|
||||
| MITHOME-26 | Analytics integráció (Plausible / GA4) | 📋 |
|
||||
|
||||
---
|
||||
|
||||
## Technikai Stack
|
||||
- **Frontend**: Next.js 14, TypeScript, Tailwind CSS
|
||||
- **Frontend**: Next.js 15, TypeScript, Tailwind CSS 4
|
||||
- **Backend**: Next.js API Routes
|
||||
- **Database**: MongoDB
|
||||
- **Database**: MongoDB (Mongoose ODM)
|
||||
- **Logging**: Winston + Loki
|
||||
- **Monitoring**: Grafana
|
||||
- **Deployment**: Dokploy
|
||||
- **Testing**: Jest, React Testing Library
|
||||
- **Project Management**: Linear (elsődleges)
|
||||
- **Project Management**: Plane MITHOME (elsődleges)
|
||||
|
||||
---
|
||||
|
||||
## Fejlesztési Parancsok
|
||||
|
||||
### Hagyományos fejlesztés
|
||||
```bash
|
||||
# Fejlesztői szerver indítása
|
||||
# Fejlesztői szerver
|
||||
cd proto && npm run dev
|
||||
|
||||
# Tesztek futtatása
|
||||
# Tesztek
|
||||
cd proto && npm test
|
||||
cd proto && npm run test:all
|
||||
|
||||
# Build készítése
|
||||
# Build
|
||||
cd proto && npm run build
|
||||
```
|
||||
|
||||
### Docker fejlesztői környezet
|
||||
```bash
|
||||
# Docker stack indítása (teljes környezet)
|
||||
# Docker stack
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
|
||||
# Docker stack leállítása
|
||||
docker-compose -f docker-compose.dev.yml down
|
||||
|
||||
# Logok követése
|
||||
docker-compose -f docker-compose.dev.yml logs -f
|
||||
|
||||
# Alkalmazás újraépítése
|
||||
docker-compose -f docker-compose.dev.yml up --build -d
|
||||
|
||||
# Teljes tisztítás (adatok törlése)
|
||||
docker-compose -f docker-compose.dev.yml down -v
|
||||
```
|
||||
|
||||
### Elérhető szolgáltatások (Docker)
|
||||
@@ -132,43 +92,10 @@ docker-compose -f docker-compose.dev.yml down -v
|
||||
- **MongoDB UI**: http://localhost:8081 (admin/password123)
|
||||
- **Grafana**: http://localhost:3001 (admin/admin123)
|
||||
- **Loki**: http://localhost:3100
|
||||
- **MongoDB**: mongodb://admin:password123@localhost:27017/admin
|
||||
|
||||
## Fontos Megjegyzés
|
||||
A Linear az authoritative project management rendszer. Ez a fájl csak lokális referencia, mindig ellenőrizd a Linear-t az aktuális státuszért és priorításokért.
|
||||
---
|
||||
|
||||
## Frissítési Napló
|
||||
- **2025-09-05**: TODO.md fájl létrehozása, Linear integráció megjegyzésekkel
|
||||
- **2025-09-05**: Szinkronizáció Linear Website Development projekttel - aktuális státuszok frissítve
|
||||
- **2025-09-05**: Nagyobb implementációs mérföldkő - ZEE-31, ZEE-32, ZEE-33 befejezve, mobil navigáció és contact API implementálva
|
||||
- **2025-09-05**: Docker fejlesztői környezet implementálva - ZEE-34, ZEE-35 befejezve, teljes stack (Next.js + MongoDB + Monitoring) működik
|
||||
## Szinkronizálás Utmutató
|
||||
|
||||
A TODO.md és Linear között párhuzamos vezetéshez használd a `linear-sync.js` scriptet:
|
||||
|
||||
```bash
|
||||
# API kulcs hozzáadása a .env fájlhoz (Linear settings -> API)
|
||||
# Szerkesd a .env fájlt és add hozzá:
|
||||
# LINEAR_API_KEY=lin_api_your_actual_key_here
|
||||
|
||||
# Szinkronizálás futtatása
|
||||
node linear-sync.js
|
||||
|
||||
# vagy
|
||||
./linear-sync.js
|
||||
```
|
||||
|
||||
A script:
|
||||
- Megkeresi a TODO.md-ben hiányzó Linear ticket-eket
|
||||
- Létrehozza ezeket a Linear-ben
|
||||
- Frissíti a Linear ticket státuszokat a TODO alapján
|
||||
- Visszairja a Linear ticket számokat a TODO.md-be
|
||||
|
||||
### ✅ Szinkronizáció állapota:
|
||||
Minden feladat megtalálható a Linear-ben megfelelő ticket számmal. A TODO.md mostantól teljesen szinkronban van a Linear Website Development projekttel.
|
||||
|
||||
**Befejezett ticketek:** ZEE-28, ZEE-30, ZEE-31, ZEE-32, ZEE-33, ZEE-34, ZEE-35
|
||||
**Backlog ticketek:** ZEE-29, ZEE-36-46
|
||||
**Duplikált ticketek eltávolítva:** ZEE-27 (duplikáció a ZEE-28-hoz képest)
|
||||
|
||||
**Utolsó szinkronizáció:** 2025-01-23 - ZEE-29 (Tailwind + layout) és JSON content management befejezése
|
||||
- **2026-04-26**: Átállás Linear → Plane (MITHOME projekt). TODO.md teljes újraírva, 26 issue szinkronizálva.
|
||||
- **2025-01-23**: ZEE-29 (Tailwind + layout) és JSON content management befejezése (Linear)
|
||||
- **2025-09-05**: Docker fejlesztői környezet implementálva
|
||||
Reference in New Issue
Block a user