@horka/app-forge 0.1.0

package/templates/packs/vapor-api/docs-architecture/GOTCHAS_LINUX_SWIFT.md

@@ -0,0 +1,109 @@
+# GOTCHAS — Swift on Linux (the deployment target)
+
+Server-side Swift develops on macOS but RUNS on Linux, and the two are not the same
+platform. Every entry below was paid for in production by a real team. Format:
+**Symptom → Cause → Fix.** Add new entries with evidence only.
+
+## 1. URLSession crashes on Linux — use AsyncHTTPClient, always
+
+- **Symptom:** intermittent hard crashes in production: `Illegal instruction`, libcurl
+  error 43 (`CURLE_BAD_FUNCTION_ARGUMENT`), memory corruption under concurrent load.
+  Everything green on macOS.
+- **Cause:** on Linux, `URLSession` comes from `FoundationNetworking` — a libcurl-based
+  reimplementation with known race conditions in handle configuration. It is NOT the
+  battle-tested Darwin stack you developed against.
+- **Fix:** ONE HTTP client for the whole service: **AsyncHTTPClient**, reached through
+  Vapor's managed instance `app.http.client.shared`. Inject it (init parameter or a
+  config actor) into every client target — never construct ad-hoc `HTTPClient()`
+  instances per call (each spawns an event loop group; you leak threads and FDs and must
+  manage shutdown yourself).
+  ```swift
+  var request = HTTPClientRequest(url: url)
+  request.method = .GET
+  let response = try await httpClient.execute(request, timeout: .seconds(30))
+  ```
+  Enforcement is a grep: `grep -rn "URLSession" Sources/` must return nothing.
+
+> 📖 **War story:** a production team migrated 18 call sites from URLSession to injected
+> AsyncHTTPClient after chasing "random" illegal-instruction crashes for weeks. The
+> crashes stopped the day the migration shipped.
+
+## 2. Non-Sendable containment — Fluent entities stay in the request scope
+
+- **Symptom:** Swift 6 data-race diagnostics around model classes; or, with checking
+  silenced, corrupted field values under load.
+- **Cause:** Fluent models are mutable `final class`es marked `@unchecked Sendable` —
+  the annotation silences the compiler but provides zero runtime safety. An entity that
+  crosses a task boundary (cached in a singleton, captured by a background task, passed
+  between requests) is a shared-mutable-state bug.
+- **Fix:** containment. Entities are born in a repository call and die at the controller
+  edge, mapped to a `Sendable` DTO struct (`DTO.Output(entity:)`). Nothing reference-typed
+  leaves the request. Caches and queues hold value types only.
+
+## 3. Migration ordering only fails on FRESH databases
+
+- **Symptom:** first deploy to a new environment crashes at boot:
+  `relation "teams" does not exist`. Every developer machine and the long-lived staging
+  DB boot fine.
+- **Cause:** Fluent executes migrations in REGISTRATION order. Incrementally-migrated
+  databases already have every table, so a wrong order hides for months until a
+  from-scratch run (new region, new developer, disaster recovery — the worst possible
+  moments).
+- **Fix:** central, explicit, commented registration in `configure.swift`: foreign-key
+  targets first. Any change to migrations gets verified against a scratch database
+  (drop + full migrate) before merge.
+
+## 4. Background work must not borrow request-scoped resources
+
+- **Symptom:** intermittent `connection closed` / pool errors in work spawned from a
+  handler with `Task { … req.db … }` or `Task.detached`; failures cluster under load and
+  vanish locally.
+- **Cause:** `req.db`, `req.client`, `req.logger` live in the request's lifecycle. The
+  response returns, the request's resources are released, the orphaned task keeps using
+  them.
+- **Fix:** work that outlives the response goes through a persistent queue (Vapor Queues
+  with a database/Redis driver) — survives restarts, retries on failure, uses its own
+  connections. For app-lifetime (not request-lifetime) work only, use `app.db`/`app.logger`
+  explicitly and deliberately.
+
+## 5. `hashValue` is per-process — never persist or compare it across runs
+
+- **Symptom:** cache keys, ETags, or dedupe markers computed with `hashValue` never match
+  after a restart or between replicas; conditional requests never return 304.
+- **Cause:** Swift's `Hashable` seeds its hash per process BY DESIGN.
+- **Fix:** stable identity only: SHA-256 of the bytes, or a `version`/`updatedAt` column.
+  See the ETag entry in `ANTI_PATTERNS.md` — this exact bug shipped to production.
+
+## 6. macOS-green is not done — gate on Linux
+
+- **Symptom:** CI on macOS passes; the Docker deploy crashes or behaves differently
+  (Foundation gaps, file-path case sensitivity, locale/encoding differences).
+- **Cause:** Foundation on Linux is a different implementation with a different surface;
+  the filesystem is case-sensitive; the C library differs.
+- **Fix:** the Linux gate is one command and runs before every ship:
+  ```bash
+  docker run --rm -v "$PWD:/src" -w /src swift:6.2-noble swift test
+  ```
+  CI runs the test job in a Swift Linux container, matching the Dockerfile's Swift version.
+
+## 7. `MetricsSystem.bootstrap` may only run once per process
+
+- **Symptom:** the app runs fine; the test suite crashes with
+  `metrics system can only be initialized once per process` on the second booted app.
+- **Cause:** swift-metrics enforces single bootstrap, but tests create many
+  `Application`s, and bootstrap was wired per-application.
+- **Fix:** anchor the registry + bootstrap to the process with a lazy `static let`
+  (`MetricsRegistry.shared` in the Monitoring target) — thread-safe by language
+  guarantee, runs exactly once, every app shares the registry.
+
+## 8. `.env` is loaded from the WORKING DIRECTORY
+
+- **Symptom:** `Missing environment variable …` fatal at boot although `.env` exists and
+  is correct — typically when launching from an IDE, a systemd unit, or a script that
+  `cd`s elsewhere.
+- **Cause:** Vapor's `Environment.detect()` reads `.env` relative to the process working
+  directory, not the binary location or the repo root.
+- **Fix:** always launch from the project root locally; in production don't use `.env`
+  files at all — the orchestrator injects real environment variables. The fail-fast
+  `AppConfig.Key.get` turns this mistake into an immediate, named boot error instead of
+  weird half-configured behavior.

package/templates/packs/vapor-api/docs-architecture/OPS.md

@@ -0,0 +1,102 @@
+# OPS — Logging, Metrics, Docker, Runtime Configuration
+
+How this service behaves in production. Everything here is already wired in the skeleton;
+this doc explains the contract so changes don't silently break operations.
+
+## 1. Logging
+
+Two modes, decided once in `entrypoint.swift`:
+- **Development**: Vapor's human-readable text handler.
+- **Release**: `JSONLogHandler` (Monitoring target) — ONE JSON object per line on stdout,
+  metadata flattened to top-level keys. Loki/Grafana/CloudWatch parse it without config.
+
+Level precedence: `--log` CLI flag → `LOG_LEVEL` env var → default (`notice` in
+production, `info` elsewhere). **The level is never hardcoded** — a hardcoded `.debug`
+in configure once shipped to a production fleet and flooded the log store; runtime config
+exists precisely so ops can turn verbosity up DURING an incident without a redeploy.
+
+`HTTPLoggingMiddleware` (Monitoring) replaces Vapor's default route logger:
+- adds `duration_ms` to every request log (monotonic clock — NTP-jump safe),
+- skips `/health` and `/metrics` (probes fire every few seconds; logging them buries
+  real traffic and inflates storage for zero information).
+
+> ⚠️ **Gotcha:** Symptom — log volume explodes after adding an uptime monitor. Cause —
+> probe endpoints logged like user traffic. Fix — exclusion list in the middleware init,
+> not grep-filtering in the log store (you pay for ingestion before filtering).
+
+## 2. Metrics
+
+- Backend: swift-metrics API + Prometheus exporter. Feature code NEVER touches the
+  metrics API directly — it calls Monitoring helpers (e.g. `recordHTTPError`), so the
+  backend stays swappable and metric names stay consistent.
+- The registry and `MetricsSystem.bootstrap` are **process-global** (`MetricsRegistry.shared`,
+  a lazy `static let`). Bootstrap may only run once per process; tests boot many apps.
+- `/metrics` endpoint contract:
+  - Bearer token from `METRICS_TOKEN`, compared with `constantTimeCompare` — a plain
+    `==` leaks token length and prefix timing to an attacker who can measure latency.
+  - Monitoring disabled → 503 (scrapers alarm loudly instead of charting zeros).
+  - `/health` stays unauthenticated (load balancers can't do auth); it returns liveness
+    ONLY — no version, no dependency status, nothing enumerable.
+
+## 3. Docker — the production image
+
+`Dockerfile` is multi-stage; each choice is load-bearing:
+
+| Choice | Why |
+|---|---|
+| Dependencies resolved in their own layer | `Package.*` unchanged → deps layer cached → rebuilds in seconds |
+| `swift build -c release --static-swift-stdlib` | run image needs no Swift runtime — smaller, fewer CVEs to track |
+| `-Xlinker -ljemalloc` (dynamic) | server-grade allocator; the STATIC jemalloc is incompatible with the static Swift runtime |
+| `swift-backtrace-static` copied + `SWIFT_BACKTRACE` env | crashes print symbolized backtraces in the container — without it a production crash is one unusable line |
+| dedicated `vapor` user, `USER vapor:vapor` | the API never runs as root; a container escape lands in an unprivileged account |
+| `Public/`/`Resources/` copied `chmod -R a-w` | runtime can't mutate its own assets |
+| `ARG/ENV LOG_LEVEL` | verbosity is deploy-time AND runtime configurable |
+| `CMD serve --env production --hostname 0.0.0.0 --port 8080` | binds all interfaces INSIDE the container; the host decides exposure |
+
+Build & run:
+```bash
+docker build -t my-service .
+docker run --rm -p 8080:8080 --env-file .env my-service
+```
+
+> ⚠️ **Gotcha:** Symptom — TLS calls to external APIs fail only in the container
+> (`unable to get local issuer certificate`). Cause — minimal run images ship without CA
+> roots. Fix — `ca-certificates` stays in the run-image package list; never "fix" this by
+> disabling certificate verification.
+
+## 4. Runtime configuration
+
+- All config flows through `AppConfig` (typed, fail-fast — see CONVENTIONS.md §3).
+  A misconfigured service must die at boot with the variable's name in the crash log;
+  orchestrators surface boot crashes immediately, while a lazy nil surfaces as a 3 a.m.
+  500 storm.
+- Secrets (DB password, metrics token, API keys) come from the orchestrator's secret
+  store; `env_dist` documents the variable, never the value.
+- Deploy checklist for any config change:
+  1. `AppConfig.Key` case + typed property
+  2. `env_dist` line
+  3. every compose/CI manifest
+  4. `bash scripts/validate-env-vars.sh` green
+  5. secret created in the deploy environment BEFORE the deploy
+
+## 5. Database operations
+
+- Migrations run at boot (`app.autoMigrate()` in configure). Registration order is
+  load-bearing — see `ARCHITECTURE.md` §5 and GOTCHAS.
+- Connection pool: `maxConnectionsPerEventLoop` × event loops (≈ CPU cores) = total
+  connections per replica. Size against the database's `max_connections` BEFORE scaling
+  replicas, not after the pool exhaustion incident.
+- Tests run on in-memory SQLite (zero infra), but SQLite is not PostgreSQL: anything
+  using PostgreSQL-specific SQL needs a CI job against a real PostgreSQL service
+  container before release.
+
+## 6. Shipping checklist
+
+```bash
+swift test                                                        # host gate
+docker run --rm -v "$PWD:/src" -w /src swift:6.2-noble swift test # Linux gate (the real target)
+bash scripts/validate-env-vars.sh                                 # config drift
+bash scripts/generate-error-codes.sh && git diff --exit-code docs/ERROR_CODES.md  # error doc current
+docker build -t my-service . && docker run --rm -p 8080:8080 --env-file .env my-service
+curl -s localhost:8080/health                                     # eyes-on proof
+```

package/templates/packs/vapor-api/env_dist

@@ -0,0 +1,29 @@
+# {{PROJECT_NAME}} — environment template
+#
+# Copy to .env for local development (Vapor loads .env automatically from the working
+# directory). NEVER commit .env or put real production values here.
+#
+# CONTRACT: every variable below has a matching case in AppConfig.Key
+# (Sources/App/Configure/AppConfig.swift) and vice versa — except LOG_LEVEL, which is
+# read in entrypoint.swift BEFORE config exists. scripts/validate-env-vars.sh enforces
+# the cross-check; run it whenever you touch configuration.
+
+# Log level: trace|debug|info|notice|warning|error|critical (never hardcoded in code)
+LOG_LEVEL=debug
+
+# Database (PostgreSQL)
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_USERNAME=vapor_username
+DATABASE_PASSWORD=vapor_password
+DATABASE_NAME=vapor_database
+
+# CORS — exact origin of the frontend allowed to call this API
+ALLOWED_ORIGIN=http://localhost:3000
+
+# Monitoring (see docs-architecture/OPS.md)
+# When MONITORING_ENABLED=true, METRICS_TOKEN MUST be non-empty — boot fails fast otherwise
+# (an empty token would leave /metrics returning 401 forever). Leave it blank only while
+# MONITORING_ENABLED stays false.
+MONITORING_ENABLED=false
+METRICS_TOKEN=

package/templates/packs/vapor-api/gitignore

@@ -0,0 +1,7 @@
+.build/
+.swiftpm/
+.env
+.env.*
+db.sqlite*
+xcuserdata/
+DerivedData/

package/templates/packs/vapor-api/pack.json

@@ -0,0 +1,11 @@
+{
+  "id": "vapor-api",
+  "label": "Swift API — Vapor 4 / Fluent / PostgreSQL",
+  "languages": ["swift"],
+  "idPrompt": "Service identifier",
+  "requirements": [
+    "Swift 6 toolchain (Xcode 16+ or swift.org toolchain)",
+    "Docker (local PostgreSQL, production image builds, Linux test runs)"
+  ],
+  "notes": "Boots day one: `swift test` runs the full stack on in-memory SQLite — no database needed. First real run: `cp env_dist .env`, start a local PostgreSQL, `swift run App serve`."
+}

package/templates/packs/vapor-api/scripts/generate-error-codes.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Generates docs/ERROR_CODES.md from the typed error enums in Sources/App/Error/Failed.swift.
+# THE DOC IS GENERATED — never edit it by hand; edit the enum and re-run this script.
+#
+# Depends on two CONVENTIONS.md rules:
+#   - one enum per HTTP status, conforming to CustomError
+#   - convert() stays on ONE line: `func convert() -> HTTPStatus { .badRequest }`
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+FAILED_SWIFT="$PROJECT_ROOT/Sources/App/Error/Failed.swift"
+OUTPUT="$PROJECT_ROOT/docs/ERROR_CODES.md"
+
+mkdir -p "$PROJECT_ROOT/docs"
+
+status_code() {
+    case "$1" in
+        badRequest) echo 400 ;;
+        unauthorized) echo 401 ;;
+        paymentRequired) echo 402 ;;
+        forbidden) echo 403 ;;
+        notFound) echo 404 ;;
+        conflict) echo 409 ;;
+        gone) echo 410 ;;
+        unprocessableEntity) echo 422 ;;
+        tooManyRequests) echo 429 ;;
+        internalServerError) echo 500 ;;
+        notImplemented) echo 501 ;;
+        serviceUnavailable) echo 503 ;;
+        *) echo "?" ;;
+    esac
+}
+
+{
+    echo "# Error Codes — GENERATED FILE, DO NOT EDIT"
+    echo ""
+    echo "> Source of truth: \`Sources/App/Error/Failed.swift\`."
+    echo "> Regenerate with \`./scripts/generate-error-codes.sh\`."
+    echo ""
+    echo "Response body shape: \`{\"code\": <http status>, \"name\": \"<case>\", \"description\": \"<reason>\"}\`"
+    echo ""
+    echo "| name | HTTP | category |"
+    echo "|---|---|---|"
+} > "$OUTPUT"
+
+current_enum=""
+cases=""
+
+flush() {
+    [ -z "$current_enum" ] && return
+    code=$(status_code "$1")
+    for c in $cases; do
+        echo "| \`$c\` | $code | $current_enum |" >> "$OUTPUT"
+    done
+    cases=""
+}
+
+while IFS= read -r line; do
+    if [[ "$line" =~ enum[[:space:]]+([A-Za-z]+):[[:space:]]*CustomError ]]; then
+        current_enum="${BASH_REMATCH[1]}"
+        cases=""
+    elif [[ "$line" =~ ^[[:space:]]+case[[:space:]]+([a-zA-Z]+) ]]; then
+        cases="$cases ${BASH_REMATCH[1]}"
+    elif [[ "$line" =~ convert\(\)[[:space:]]*-\>[[:space:]]*HTTPStatus[[:space:]]*\{[[:space:]]*\.([a-zA-Z]+) ]]; then
+        flush "${BASH_REMATCH[1]}"
+        current_enum=""
+    fi
+done < "$FAILED_SWIFT"
+
+echo "Generated $OUTPUT"

package/templates/packs/vapor-api/scripts/validate-env-vars.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Cross-checks the typed config (AppConfig.Key) against env_dist and every deploy
+# manifest that exists. A variable that exists in code but not in a manifest is a
+# production crash waiting for the next deploy — fail loudly here instead.
+#
+# Usage: ./scripts/validate-env-vars.sh   (from anywhere; exits 1 on any mismatch)
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+APP_CONFIG="$PROJECT_ROOT/Sources/App/Configure/AppConfig.swift"
+ENV_DIST="$PROJECT_ROOT/env_dist"
+
+# Manifests are optional — checked only if present. Add yours here as the project grows.
+MANIFESTS=(
+    "$PROJECT_ROOT/docker-compose.yml"
+    "$PROJECT_ROOT/deploy/docker-compose.yml"
+    "$PROJECT_ROOT/.github/workflows/deploy.yml"
+    "$PROJECT_ROOT/.github/workflows/test.yml"
+)
+
+echo "Validating environment variables against AppConfig.Key..."
+echo ""
+
+# Extract case names from the AppConfig.Key enum ("case VARIABLE_NAME").
+ENV_VARS=$(grep -E '^\s*case [A-Z_]+' "$APP_CONFIG" | sed 's/.*case //' | sed 's/[^A-Z_].*//' | sort -u)
+
+if [ -z "$ENV_VARS" ]; then
+    echo -e "${RED}No Key cases found in $APP_CONFIG — wrong path?${NC}"
+    exit 1
+fi
+
+ALL_VALID=true
+
+for var in $ENV_VARS; do
+    if ! grep -q "^${var}=" "$ENV_DIST" 2>/dev/null; then
+        echo -e "${RED}MISSING in env_dist: ${var}${NC}"
+        ALL_VALID=false
+    fi
+    for manifest in "${MANIFESTS[@]}"; do
+        if [ -f "$manifest" ]; then
+            if ! grep -Eq "${var}[:=]" "$manifest" 2>/dev/null; then
+                echo -e "${RED}MISSING in ${manifest#"$PROJECT_ROOT"/}: ${var}${NC}"
+                ALL_VALID=false
+            fi
+        fi
+    done
+done
+
+# Reverse check: env_dist entries that no longer exist in code (drift the other way).
+# LOG_LEVEL is exempt — read in entrypoint.swift before AppConfig exists.
+for var in $(grep -E '^[A-Z_]+=' "$ENV_DIST" | cut -d= -f1 | sort -u); do
+    [ "$var" = "LOG_LEVEL" ] && continue
+    if ! echo "$ENV_VARS" | grep -q "^${var}$"; then
+        echo -e "${YELLOW}STALE in env_dist (no AppConfig.Key case): ${var}${NC}"
+    fi
+done
+
+echo ""
+if [ "$ALL_VALID" = true ]; then
+    echo -e "${GREEN}All environment variables are consistent.${NC}"
+else
+    echo -e "${RED}Fix the mismatches above before committing.${NC}"
+    exit 1
+fi