# Tinyforge

## Dev Server

Start/restart with: `./scripts/dev-server.sh`

- Runs on port **8090** (avoids 8080 conflict with other local services)
- Auto-generates `ENCRYPTION_KEY` if not set
- Default login: `admin` / `admin123`
- Override port: `LISTEN_ADDR=:9000 ./scripts/dev-server.sh`

## Frontend

- **Boolean inputs use `ToggleSwitch`** (`$lib/components/ToggleSwitch.svelte`) — the slide-style switch is the unified control across the WebUI. Do not introduce raw `<input type="checkbox">` elements; place a `<ToggleSwitch>` next to a label/help block instead.
- **Confirmations & destructive actions use `ConfirmDialog`** (`$lib/components/ConfirmDialog.svelte`) — never native `window.confirm` / `alert`. For navigation guards (e.g. the unsaved-changes prompt on `/apps/new`), `cancel()` the navigation in `beforeNavigate`, open `ConfirmDialog`, and re-issue the navigation with a bypass flag on confirm. Native `beforeunload` is acceptable only for hard tab-close/reload, where the browser forbids custom UI.
- **Source-config shape: `$lib/workload/sourceForms.ts`** is the single source of truth (seed/serialize/validity for image/compose/static/dockerfile), consumed by both `/apps/new` and `/apps/[id]`. Don't re-inline seed/serialize logic.
- **"App" = workload with `source_kind !== ''`.** Triggers are first-class bindings (`workload_trigger_bindings`), NOT on the workload row — never gate app lists/counts on `trigger_kind` (it's empty for plugin workloads). Legacy pre-cutover `kind:project/stack/site` rows have an empty `source_kind` and must be excluded everywhere.
- **i18n parity is mandatory** — every key in BOTH `web/src/lib/i18n/{en,ru}.json`. A missing key is NOT a build error (`$t` returns the key string), so verify parity manually.

## Backend

- **Per-workload deploy lock.** Every deploy entrypoint (API deploy, rollback, promote,
  generic-hooks, webhook trigger dispatch) funnels through `deployer.DispatchPlugin`, which
  holds a per-workload `keyedmutex` lock (`internal/keyedmutex`) for the whole dispatch;
  `DispatchTeardown` takes it too. This serializes all container/volume mutation per workload.
  Do NOT add a deploy/teardown path that bypasses `DispatchPlugin`. Operations that must run
  a deploy *while already holding* the lock (volume-snapshot restore) use
  `Deployer.LockWorkload` + `RedeployLocked` (the unlocked dispatch) — calling `DispatchPlugin`
  under the held lock would deadlock (Go mutexes are not reentrant). `activeWg` is a global
  drain barrier for shutdown, NOT a per-workload lock.
- **Volume snapshot restore** lives in `volsnap.Engine.Restore` (engine-owned, not the API
  handler): preflight re-resolves volumes from the workload's CURRENT config (never the
  snapshot manifest — that's tamper-influenceable) → lock → stop → extract-to-tmp →
  pre-restore snapshot → journal → atomic rename swap → redeploy. A startup
  `RecoverInterruptedRestores` sweep replays the journal after a crash; it MUST be wired (with
  `SetLifecycle`) before the API serves. The archive extractor treats the tar as untrusted
  (zip-slip/type-allowlist/bomb-cap); the endpoint requires an `X-Confirm-Restore: <sid>`
  header (CSRF), like the DB restore.

## Build & Test

- Frontend (from `web/`): `npm run check` (svelte-check — expect 0 errors), `npm run build`, `npm run test` (vitest; pure-logic units like `sourceForms.test.ts`).
- Backend (repo root): `go build ./...`, `go vet ./internal/...`, `go test ./internal/...`.
- `./scripts/dev-server.sh` rebuilds the SPA + restarts the Go server on :8090; it kills the prior process, so a previous background dev-server task reporting **exit 1 is expected**, not a failure.