diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000..f90451e --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,348 @@ +# 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í