zima-apps/AGENTS.md

AGENTS.md

Detta dokument styr hur agenter och utvecklare arbetar i detta repo. Fokus: korrekthet, låg risk och underhållbarhet.

1) Syfte och prioritet

• Gäller hela repot.
• Kompletterar globala agentinstruktioner.
• Vid konflikt gäller striktare regel.

2) Repo-invarianter

• Appfiler ligger under Apps/<app-id>/.
• Varje app ska minst ha:
  • docker-compose.yaml
  • README.md (syfte, portar, volymer, privilegier, risker)
• Compose ska ha giltig top-level name (gemener + bindestreck).
• Om container_name används måste den vara max 32 tecken och bara innehålla 0-9, a-z, A-Z, _, -.
• Endast .yaml används i repot (aldrig .yml).
• Swap-filer (t.ex. *.swp, *.swo) ska alltid ignoreras och får aldrig committas.

3) Säkerhetsbaseline (Compose)

MUST:

• Pinna images till explicit version eller digest.
• Inte använda :latest.
• Hålla volymer snäva (/DATA/AppData/$AppID/...).
• Vid förslag/byte av image: måste imagen verifieras online (manifest/tag finns i registry) innan merge.
• Använd App/_template som grund om inget annat anges.
• deply.resources.reservations ska sättas till något passande. Detta kommer även parsas av ZimaOS webui

SHOULD:

• security_opt: ["no-new-privileges:true"]
• cap_drop: ["ALL"] när appen tillåter det.

Högrisk-inställningar är tillåtna men kräver varning och motivering:

• privileged: true
• network_mode: host
• mount av Docker-socket (/var/run/docker.sock)

Om någon högrisk-inställning används måste appens README.md innehålla:

• varför det behövs,
• vilka alternativ som utvärderats,
• vilka risker det innebär.

4) Arbetsflöde för ändringar

• Små, reviewbara ändringar först.
• Beskriv säkerhetspåverkan i PR.
• Lokal validering är rekommenderad under utveckling:

./scripts/validate-appstore.sh

• Lokal validering är inte blockerande för varje enskild commit.

5) Obligatorisk release-checklista

Inför release/publicering måste följande vara uppfyllt:

1. ./scripts/validate-appstore.sh körd med Validation OK.
2. Ingen app använder image: ...:latest.
3. x-casaos metadata är satt och konsekvent.
4. Appens README.md är uppdaterad.
5. Eventuella högrisk-inställningar är tydligt motiverade.

6) Review-krav

PR som ändrar appar ska explicit ange:

• vilka app-id:n som påverkas,
• säkerhetsrisk (låg/medel/hög),
• om högrisk-inställningar introduceras eller ändras.

7) Testkrav för containerappar

För nya appar eller större ändringar i befintliga appar (routing, discovery, auth, nätverk, secrets, cert-hantering) ska integrationstester ingå.

Minimikrav:

• Testa med mockade externa gränser (t.ex. Docker API, reverse proxy API, DNS/API-provider), så testerna är reproducerbara lokalt.
• Verifiera minst ett fail-closed-scenario (saknad/ogiltig secret, API-fel, otillåten metadata) där appen inte exponerar tjänster oavsiktligt.
• Verifiera att endast explicit tillåtna containrar/endpoints exponeras.

Tester ska dokumenteras i appens README.md med exakt körkommando.

8) Branch-namnstandard

När en ny branch skapas ska formatet vara:

<appnamn>/<initial|bugfix|update>/<detalj>

Regler för <detalj>:

• initial: max 5 ord som beskriver vad som byggs.
• bugfix: vad som fixas (kort och konkret).
• update: versionsuppdatering i formen vX.Y.Z-to-vA.B.C.

9) Parallellt agentarbete och git-scope

• När en ny app skapas ska en ny mapp alltid skapas under Apps/<app-id>/.
• Flera agenter kan arbeta samtidigt. Fråga alltid innan du skapar ny branch eller byter branch, för att undvika krockar.
• git add och git commit får endast omfatta filer i den egna appens undermapp under Apps/<app-id>/.
• För varje fil som en agent tänker ändra ska agenten först skapa en tom låsfil: <filnamn>.agent_wip.
• Om <filnamn>.agent_wip redan finns ska agenten vänta 60 sekunder och kontrollera igen.
• Upprepa väntan i upp till 10 minuter (10 försök). Om låsfilen fortfarande finns efter 10 minuter: avbryt och be användaren om beslut.
• När agenten är klar med filen ska motsvarande <filnamn>.agent_wip tas bort direkt.
• Låsfilen ska tas bort även vid fel/avbrott så långt det går, för att undvika falska lås.

10) Verifieringsdokument när app är redo

När en app bedöms som "redo" ska appmappen innehålla en verifieringsfil:

• Apps/<app-id>/HOW_TO_VERIFY.md

Filen ska vara praktiskt körbar och innehålla:

• tydliga förutsättningar (miljö, DNS, secrets, beroenden),
• positiva testfall med förväntade resultat,
• minst ett fail-closed/negativt testfall,
• exakta kommandon för att verifiera DNS, nät och TLS,
• en sektion "data att samla" för snabb Codex-felsökning.

Sektionen "data att samla" ska minst täcka:

• versions-/buildinfo (appversion, branch/commit eller zip + checksum),
• relevant konfiguration (med maskade secrets),
• loggar från berörda containers,
• konkreta felobservationer (hostname, tidpunkt, förväntat vs faktiskt beteende).

11) Release- och publiceringsarbetsflöde

Steg 1: Branch

Skapa branch enligt format i sektion 8: <appnamn>/<initial|bugfix|update>/<detalj>

Steg 2: Verifiera images (innan commit)

Kontrollera att alla Docker-images är tillgängliga online. Scriptet build-appstore-zip.sh verifierar automatiskt -- kör det för att kontrollera, eller använd:

docker manifest inspect <image:tag@sha256:...>

Steg 3: Validera lokalt

Kör validering innan commit:

./scripts/validate-appstore.sh

Steg 4: Committa ändringar

• Små, reviewbara commits.
• Separera appfiler från dist/-filer.
• Commit-meddelande: rubrik + bulletpunkter.

Steg 5: Bygg appstore-zip

./scripts/build-appstore-zip.sh

• Skapar dist/phirna-appstore.zip.
• Verifierar alla images online automatiskt.
• Genererar SHA256 checksum.
• Med CI=true eller --strict-images misslyckas bygget om en image saknas.

Steg 6: Committa dist/

Separer commit för dist/ från appfiler:

git add dist/ && git commit -m "Build appstore zip"

Steg 7: Push och PR

git push -u origin <branch>

PR ska inkludera:

• Vilka app-id som påverkas.
• Säkerhetsrisk (låg/medel/hög).
• Högrisk-inställningar vid introduktion eller förändring.