diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md deleted file mode 100644 index f90451e..0000000 --- a/scripts/AGENTS.md +++ /dev/null @@ -1,348 +0,0 @@ -# AGENTS.md - -Tento repozitář obsahuje aplikaci běžící v AppFactory. - -Tento soubor je určený pro AI asistenty, vývojáře a automatizované nástroje, které budou aplikaci upravovat. - -## Kontext AppFactory - -Aplikace běží jako Docker container spravovaný AppFactory. - -AppFactory zajišťuje: - -- vytvoření Gitea repozitáře -- webhook z Gitea do AppFactory -- build Docker image -- deploy containeru -- reverse proxy přes Caddy -- runtime variables a secrets přes environment variables -- monitoring přes health endpoint - -Aplikační repozitář nemá měnit infrastrukturu AppFactory. - -## Veřejná URL a reverse proxy - -Aplikace neběží v rootu domény. - -Veřejná URL aplikace má tvar: - -```text -https://services.csbot.cz/apps/ -``` - -Příklady: - -```text -https://services.csbot.cz/apps/test-dotnet-api -https://services.csbot.cz/apps/microsoft-365-service -``` - -Aplikace musí počítat s tím, že běží za reverse proxy. - -Nikdy nehardcoduj veřejnou doménu. - -Nikdy nehardcoduj `/apps/` do business logiky, pokud framework nabízí lepší mechanismus, například: - -- `ROOT_PATH` -- `PathBase` -- `basePath` -- OpenAPI `servers` -- Swagger route prefix -- framework-specific proxy/base URL nastavení - -## Caddy routing - -AppFactory Caddy routuje aplikace přes: - -```text -/apps/ -``` - -Typicky platí: - -```text -veřejný request: -GET /apps//contacts - -aplikace uvnitř containeru často vidí: -GET /contacts -``` - -Důvodem je použití reverse proxy route typu `handle_path`, která prefix `/apps/` odstraní před předáním do containeru. - -Aplikace proto musí být napsaná tak, aby: - -- správně obsloužila interní routy -- správně generovala dokumentaci pro veřejnou proxy cestu -- Swagger UI testování používalo veřejnou cestu s `/apps/` - -## Povinné endpointy - -Každá služba musí poskytovat: - -```text -GET /health -GET /docs -``` - -Z veřejné URL musí být dostupné jako: - -```text -GET /apps//health -GET /apps//docs -``` - -`/health` musí vracet HTTP 200, pokud je aplikace schopná přijímat provoz. - -`/docs` musí poskytovat Swagger/OpenAPI dokumentaci nebo obdobnou interaktivní dokumentaci API. - -Pokud služba není HTTP API, musí i tak poskytovat minimální HTTP health endpoint. - -## Swagger / OpenAPI pravidla - -Swagger UI a OpenAPI definice musí respektovat AppFactory reverse proxy prefix. - -Pokud aplikace běží veřejně na: - -```text -https://services.csbot.cz/apps/ -``` - -pak Swagger UI musí při testování endpointů volat stejný prefix. - -Špatně: - -```text -GET https://services.csbot.cz/contacts -``` - -Správně: - -```text -GET https://services.csbot.cz/apps//contacts -``` - -Po každé úpravě API je povinné ověřit: - -1. `/health` funguje -2. `/docs` funguje -3. Swagger UI se načte -4. Swagger UI `Try it out` volá endpointy přes `/apps/` -5. OpenAPI JSON obsahuje správný server/base path -6. Nově přidané endpointy jsou ve Swagger dokumentaci - -Pokud framework generuje OpenAPI `servers`, musí obsahovat proxy prefix. - -Příklad: - -```json -{ - "servers": [ - { - "url": "/apps/" - } - ] -} -``` - -Nesmí vzniknout stav, kdy Swagger UI vypadá správně, ale tlačítko `Try it out` volá endpointy bez `/apps/`. - -## ROOT_PATH / PathBase - -AppFactory může aplikaci předávat environment variable: - -```text -ROOT_PATH=/apps/ -``` - -Použití závisí na frameworku. - -### .NET - -V ASP.NET Core použij `UsePathBase`, pokud template nebo aplikace používá `ROOT_PATH`. - -Typicky: - -```csharp -var rootPath = Environment.GetEnvironmentVariable("ROOT_PATH"); - -if (!string.IsNullOrWhiteSpace(rootPath)) -{ - app.UsePathBase(rootPath); -} -``` - -Swagger/OpenAPI ale musí být nakonfigurovaný tak, aby `servers` odpovídaly proxy prefixu. - -Nestačí pouze přidat endpoint `/docs`. - -Je nutné ověřit i Swagger `Try it out`. - -### Python / FastAPI - -FastAPI typicky používá `root_path`. - -Aplikace musí zajistit, že dokumentace a OpenAPI schema respektují proxy prefix. - -### Node.js / Express - -Express aplikace musí počítat s reverse proxy prefixem. - -Pokud se používá Swagger UI, musí být OpenAPI `servers` nebo Swagger konfigurace nastavené tak, aby testovací requesty šly přes `/apps/`. - -## Variables a secrets - -AppFactory spravuje variables a secrets přes portál. - -Portál ukládá hodnoty do DB a generuje runtime `.env` soubor aplikace. - -Aplikace je čte jako environment variables. - -Příklady: - -### .NET - -```csharp -var value = Environment.GetEnvironmentVariable("MY_VARIABLE"); -var optionalValue = builder.Configuration["OPTIONAL_VARIABLE"] ?? "default"; -``` - -### Python - -```python -import os - -value = os.getenv("MY_VARIABLE") -``` - -### Node.js - -```js -const value = process.env.MY_VARIABLE; -``` - -Secrets se nikdy nesmí: - -- commitovat do repository -- zapisovat do README -- vypisovat do logu -- vracet z běžných endpointů -- zobrazovat ve Swagger příkladech -- ukládat do zdrojového kódu -- hardcodovat - -Testovací endpointy, které vrací variables nebo secrets, se smí používat pouze dočasně pro ověření a musí být odstraněny před produkčním použitím. - -## Docker a port - -Aplikace musí poslouchat na portu definovaném AppFactory šablonou nebo metadaty aplikace. - -Port neměň bez odpovídající úpravy AppFactory konfigurace. - -Aplikace musí poslouchat na všech rozhraních containeru: - -```text -0.0.0.0 -``` - -Ne pouze na: - -```text -localhost -``` - -Dockerfile musí být deterministický a nesmí vyžadovat ruční zásahy v containeru. - -Ruční změny provedené přímo v běžícím containeru nejsou trvalé. - -## Co AI nesmí měnit v aplikačním repozitáři - -AI nesmí z aplikačního repozitáře měnit: - -- AppFactory deploy mechanismus -- Caddy konfiguraci -- Gitea webhooky -- Registry konfiguraci -- Backup/restore skripty -- Secrets storage -- Systémové soubory serveru -- AppFactory core služby -- AppFactory tools skripty - -Pokud je potřeba změnit infrastrukturu, musí se to řešit v příslušném AppFactory repozitáři, ne v repozitáři konkrétní aplikace. - -## Pravidla pro úpravy aplikace - -Před úpravou si vždy přečti: - -- `README.md` -- `AGENTS.md` -- `Dockerfile` -- hlavní vstupní soubor aplikace -- existující konfiguraci Swagger/OpenAPI -- způsob práce s environment variables - -Po úpravě ověř minimálně: - -- `/health` -- `/docs` -- upravovaný endpoint -- Swagger UI -- Swagger `Try it out` přes `/apps/` -- že container stále startuje -- že se nezměnil port bez úpravy metadat -- že secrets nejsou v logu ani ve zdrojovém kódu -- ideálně průběžně generuj dokumentaci .md do složky documentation v hlavním adresáři projektu. - -Každá změna musí zachovat kompatibilitu s AppFactory reverse proxy. - -Pokud přidáváš nový endpoint, dokumentace se musí aktualizovat současně. - -Pokud upravuješ request/response modely, Swagger/OpenAPI musí odpovídat skutečnému chování aplikace. - -## Zakázané zkratky - -Nedělej tyto věci: - -- nepřidávej endpoint, který funguje jen lokálně, ale ne přes `/apps/` -- neopravuj Swagger tak, že bude fungovat pouze na root doméně -- nevypínej Swagger kvůli proxy problému -- nevypínej health check -- nevypínej validaci secrets tím, že je začneš logovat -- nepřepisuj Dockerfile na jiný port bez úpravy AppFactory metadat -- nepřidávej hardcoded URL produkční domény do business logiky - -## Doporučený postup po změně - -Po změně aplikace ověř veřejně: - -```text -GET https://services.csbot.cz/apps//health -GET https://services.csbot.cz/apps//docs -``` - -A přes Swagger UI ověř, že testování endpointů volá URL ve tvaru: - -```text -https://services.csbot.cz/apps// -``` - -ne: - -```text -https://services.csbot.cz/ -``` - -## Shrnutí pro AI - -Nejdůležitější pravidla: - -- aplikace běží za `/apps/` -- `/health` je povinný -- `/docs` se Swaggerem je povinný -- Swagger `Try it out` musí používat `/apps/` -- OpenAPI musí mít správný base path/server -- secrets nikdy nelogovat ani necommitovat -- konfiguraci číst z environment variables -- neměnit AppFactory infrastrukturu z aplikačního repozitáře -- po každé úpravě ověř reverse proxy chování