Repo-szintű dev-szerverek

A Codumentor képes elindítani, nyilvántartani és leállítani hosszan
futó dev-szervereket az általa ismert repositorykhoz — legyen szó a
saját Django/Node/stb. projektedről, vagy magáról a Codumentorról
dogfooding közben. Egy deklaratív konfigurációs blokk, egy CLI
parancs (codumentor dev), egy közös nyilvántartás, amelyet az
admin panel listáz és kezel.

Ez az oldal azoknak szól, akik a Codumentor konfigurációját
szerkesztik, és azoknak a fejlesztőknek, akik a .codumentor/
mappát huzalozzák be a repo-jukba. Az indító egygépes és
egyfelhasználós; a több gépre szétosztott ütemezés tudatosan kimaradt
a hatókörből.

Mikor használd

Meg akarsz "nyitni" egy repót úgy, hogy közben a dev-szervere is felálljon mellé.
Magán a Codumentoron iterálsz, és tiszta, URL-en elérhető előnézetre van szükséged worktree-nként.

Ha a dev-szervered rövid életű (egy parancs, egy terminál, te
Ctrl-C-zed le, amikor végeztél), nincs erre szükséged — maradj a
megszokott munkafolyamatnál.

Konfiguráció

Vegyél fel egy dev_server blokkot a meglévő, repo-szintű
project_setup bejegyzés alá (vagy a legfelső szintű
project_setup alá, ha csak egy repód van):

project_setup:
  setup_script: .codumentor/setup.sh   # opcionális; már támogatott
  watch:                                # opcionális; már támogatott
    - requirements.txt
  dev_server:
    command: "python -m myapp serve --port ${PORT}"
    health_path: "/health"             # opcionális; GET-nek 2xx-et kell adnia
    open_url: "http://127.0.0.1:${PORT}/"
    ready_timeout_seconds: 30          # opcionális; alap: 30
    env:                                # opcionális, extra env a gyermek processznek
      MYAPP_CONFIG: dev.yaml

Mező-hivatkozás

Mező	Kötelező	Jelentés
`command`	igen	Shell-szerű parancssor. A `${PORT}` és minden más `${VAR}` hivatkozás indításkor kerül behelyettesítésre. A gyermek processz örökli a szülő környezetét, plusz megkapja a `PORT`-ot és az `env:` alatt felsorolt változókat.
`health_path`	nem	Ha meg van adva, az indító addig pollozza a `GET http://127.0.0.1:${PORT}<health_path>`-ot, amíg 2xx-et nem kap (vagy lejár az időkorlát). Enélkül csak a TCP-accept jelzi a készenlétet.
`open_url`	nem	Az URL, amire az admin panel mutat. Alapértelmezés: `http://127.0.0.1:${PORT}/`. Ugyanúgy templatelhető, mint a `command`.
`ready_timeout_seconds`	nem	Hány másodpercig várjon az indító, mielőtt sikertelennek nyilvánítja az indulást (alap: `30`).
`env`	nem	Extra környezeti változók a gyermek processznek. Az értékek templatelhetők.

`${VAR}` templatelés

Az indító a Codumentor szokásos ${VAR} behelyettesítését használja.
Kétszer fut le:

Betöltéskor: a valós env változók — pl. ${HOME} — feloldódnak a konfigurációs fájl beolvasásakor. A ${PORT} literálként marad, mert ekkor még nincs beállítva a szülő környezetben.
Indításkor: egy második menet a dev_server blokkon, immár PORT=<lefoglalt> injektálással. A command, open_url és az env: alatti értékek itt kerülnek behelyettesítésre.

Ezért bátran keverheted a ${HOME}, ${VIRTUAL_ENV} és ${PORT}
hivatkozásokat bármelyik mezőben, és működni fog.

Port-foglalás

Az indító a :0-ra köt, kiolvassa a kernel által kiosztott portot,
majd elengedi az indítás előtt. Olcsó, és nem lehet vele
tartomány-kimerülést okozni. A portok nem stabilak az újraindítások
között — minden indítás új portot és új instance-azonosítót kap.

CLI: `codumentor dev`

Négy parancs. Mindegyik ugyanúgy értelmezi a --repo NAME
kapcsolót, mint a codumentor setup. Ha a --repo elmarad, az
indító a jelenlegi munkakönyvtárból következteti ki a repót.

codumentor dev [--repo NAME] [--no-wait]
    Lefoglal egy portot, biztosítja a project_setup naprakészségét,
    elindítja a dev_server.command-ot, regisztrálja az instance-t,
    megvárja a healthcheck-et. A --no-wait átugorja a várakozást,
    de továbbra is regisztrál.

codumentor dev status [--json]
    Felsorolja a futó instance-okat. Először kireconcileálja a
    halott PID-eket. A --json géppel feldolgozható kimenetet ad,
    amely az árva processzeket is tartalmazza.

codumentor dev stop [--repo NAME | --id ID | --all]
    SIGTERM-et küld a megfelelő instance-oknak, vár, majd időtúllépés
    esetén SIGKILL következik; a registry-bejegyzéseket eltávolítja.
    A három kapcsoló közül egyet meg kell adni — alapértelmezett
    viselkedés szándékosan nincs.

codumentor dev logs [--repo NAME | --id ID] [-f/--follow] [-n N]
    Kiírja vagy nyomon követi azt a logfájlt, amelybe egy instance ír.
    A -f kapcsolóval addig streameli az új sorokat, amíg meg nem
    szakítod, vagy le nem áll a szerver. A -n megadja, hány sort
    írjon ki kezdéshez; a -n 0 a teljes fájlt kiírja.

Logok és hogy hol találod őket

Az elindított szerver stdout és stderr kimenete a
~/.codumentor/dev-logs/<instance-id>.log fájlba kerül. A fájl
csak-hozzáfűzésű; az indító soha nem rotálja és nem üríti. Minden
indítás új azonosítót (és így új fájlt) kap, ezért a lemezhasználat
indításonként egy fájllal nő.

A codumentor dev logs -f a szokásos módja a kimenet megnézésének:

$ codumentor dev logs -f
==> /home/me/.codumentor/dev-logs/codumentor-main-58231-a1b2c3.log  [id=codumentor-main-58231-a1b2c3, repo=Codumentor, pid=12345, port=58231]  (following — Ctrl-C to stop)
INFO:     Started server process [12345]
INFO:     Uvicorn running on http://127.0.0.1:58231 (Press CTRL+C to quit)
…

A follow-ciklus tisztán kilép, amint a szerver PID-je megszűnik —
így egy összeomlott szerverre futtatott logs -f visszatér ahelyett,
hogy lefagyna.

Instance kiválasztása

Ha csak egy előnézet fut, a CLI azt használja. Ha többet futtatsz,
válassz a --repo NAME (bármely egyedi repo) vagy a --id ID
kapcsolóval (a dev status listázza az azonosítókat). A hibaüzenet
felsorolja az érvényes lehetőségeket.

Az admin oldal egy "Dev-Server Previews" panelt rajzol ki, amely a
futó instance-okat listázza:

Repo / Branch — mi fut éppen
URL — kattintható, új lapon nyitja az előnézetet
Health — élő PID + port próba, 3 másodpercenként frissül
Age — eltelt idő az indítás óta
Stop — SIGTERM-et küld ugyanazon az úton, amit a codumentor dev stop is használ

A táblázat alatt két opcionális szekció jelenhet meg:

Orphan processes — élő processzek, amelyek hordozzák a belső markerünket, de nincsenek a registry-ben (ezt akkor látod, ha törölték a registry-fájlt, miközben a szerverek még futottak). Kézi kill <pid> tipp jár hozzájuk; a plugin szándékosan soha nem öl meg semmit automatikusan.

Korlátok, soft cap és erőforrás-igény

Minden előnézet egy teljes szerverprocessz — venv, sqlite, és bármi,
amit az alkalmazásod még behúz. Az indító figyelmeztetést ír az
stderr-re, ha 3 fölötti futó instance-od van. Kemény limit nincs;
a CI és a szkriptes hívók soha nem akadnak el, csak figyelmeztetést
kapnak.

Selfdev (a Codumentor saját dev_server-e)

A codumentor-selfdev.yaml egy működő dev_server blokkal érkezik,
hogy magán a Codumentoron is dogfoodolhasd az indítót:

project_setup:
  dev_server:
    command: "${VIRTUAL_ENV}/bin/codumentor -c codumentor-selfdev.yaml api --port ${PORT}"
    health_path: "/health"
    open_url: "http://127.0.0.1:${PORT}/"

A scripts/setup-worktree.sh --dev felépít egy worktree-t (saját
venv + UI build), majd execcel egy codumentor dev-et benne. Az
admin panellel együtt worktree-nként egy sort kapsz, kattintható
URL-ekkel, és egy helyen állíthatod le mindet, amikor végeztél.

Hibaelhárítás

Tünet	Valószínű ok
`No repo … has a dev_server.command`	A használt konfiguban nincs `dev_server` blokk, vagy `--repo`-val olyan repót adtál meg, amelyikben nincs.
Health check 30 másodperc után meghiúsul	Növeld a `ready_timeout_seconds` értékét, vagy nézd meg a `codumentor dev logs`-ot — lehet, hogy a processz nem tud bindelni.
A `dev status` halott instance-t mutat	A következő CLI-hívás reconcile-passza eldobja; a `codumentor dev status` futtatása is kikényszeríti.
Árva processz a `dev status`-ban	A registry-t törölték (vagy a `CODUMENTOR_DEV_REGISTRY` átírásával máshová mutattak), miközben egy gyermek tovább futott. Kézzel öld meg a felsorolt PID-et — a plugin nem teszi.

Lásd még

Design dokumentum — a teljes terv, beleértve a fázisokat és azt, ami szándékosan kívül esik a hatókörön.