# Rozwój lokalny

Stan: fundamenty plus tryb „na sucho” (`DEMO` nieustawione): prawdziwe, tylko-odczytowe handlery `plan`, `status`, `image_tags`, `image_resolve` (`src/app/dry-run/`) i konfiguracja aplikacji z `config/apps.json`. Z `DEMO=1` działają fałszywe handlery demo. Nic nie zmienia Dockera, nie używa modelu ani skryptów starego repo.

## Uruchomienie

```bash
. ~/.nvm/nvm.sh && nvm use        # Node 24 (.nvmrc)
npm ci
npm run check                     # typecheck + lint + testy: musi być zielone przed commitem
```

Dwa procesy z jednego kodu, wspólna baza SQLite (WAL):

```bash
npm run build:web                 # frontend do dist/web (serwer go serwuje)
DEMO=1 npm run start:driver       # driver: bierze kroki z kolejki; bez DEMO=1 odmawia startu
npm run start:server              # appka: http://127.0.0.1:8080
```

Podczas pracy nad frontendem: `npm run dev:web` (Vite, proxy `/api` na port 8080).
Zmiany w kodzie backendu: `npm run dev:driver` / `npm run dev:server` (`node --watch`).

Backend działa bez kroku budowania: Node 24 uruchamia `.ts` natywnie (importy z rozszerzeniem `.ts`, bez `enum` i parametrów-właściwości; pilnuje tego `erasableSyntaxOnly`).

## Zmienne środowiskowe

| Zmienna | Domyślnie | Znaczenie |
|---|---|---|
| `DB_PATH` | `./data/queue.sqlite` | plik bazy (współdzielony przez oba procesy) |
| `HOST` / `PORT` | `127.0.0.1` / `8080` | adres serwera; w kontenerze ustaw `HOST=0.0.0.0` |
| `WEB_DIR` | `dist/web` | zbudowany frontend |
| `DRIVER_IDLE_MS` | `60000` | jak często driver sprawdza pustą kolejkę (w dev np. `1000`) |
| `DEMO` | `0` | `1` = uruchom fałszywe handlery i zasiej konfigurację demo |

Wartości zmiennych o nazwach kończących się na `TOKEN`, `SECRET`, `PASSWORD`, `API_KEY`, `_KEY` driver maskuje dosłownie w każdym `detail`.

## Układ kodu

```
src/domain   typy, reguły, porty (bez I/O)              -> nic
src/app      driver, przypadki użycia, demo handlery     -> domain
src/infra    SQLite (node:sqlite), zegar, logger         -> domain, app
src/http     Fastify, kontrakt zod, SSE                  -> domain, app, infra
src/web      Preact (przeglądarka)                       -> domain, http/contract.ts
src/main     punkty wejścia procesów, e2e                -> wszystko
src/testing  fejki portów i baza w pamięci (tylko testy)
```

Granice pilnuje ESLint (`tools/layer-rules.ts`, przetestowane w `tools/layer-rules.test.ts`). `src/main`, `src/testing` i `*.test.*` są z reguły wyłączone, bo składają warstwy.

## Wersje narzędzi

TypeScript jest przypięty do `~6.0.3`: `typescript-eslint` 8.70 deklaruje `typescript <6.1.0`, więc 7.x zepsułoby lint. Do ponownego sprawdzenia przy aktualizacji `typescript-eslint`.