@horka/app-forge 0.1.0

package/templates/packs/ts-sdk/tests/singleFlight.test.ts

@@ -0,0 +1,191 @@
+import { describe, test, expect } from 'vitest';
+import {
+  ApiError,
+  AuthClient,
+  createMemoryContext,
+  type HttpMethod,
+  type HttpTransport,
+  type RequestOptions,
+  type TokenPair,
+} from '../src/index';
+
+/**
+ * THE concurrency regression suite (SDK_CONTRACT.md §3) — non-negotiable.
+ *
+ * Pins a real production bug: refresh-on-401 without synchronization sent N
+ * simultaneous refreshes; the rotating refresh token was single-use, so N−1
+ * calls failed and randomly logged users out. The fake API below ENFORCES
+ * single-use rotation — a broken single-flight fails on behavior, not just
+ * on call counts.
+ */
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+interface FakeApiOptions {
+  refreshDelayMs?: number;
+  failRefresh?: boolean;
+  hangRefresh?: boolean;
+}
+
+function createFakeApi(options: FakeApiOptions = {}) {
+  let validAccess = 'access-0';
+  let validRefresh = 'refresh-1';
+  let refreshCalls = 0;
+
+  const transport: HttpTransport = {
+    async request<T>(method: HttpMethod, path: string, reqOptions: RequestOptions = {}): Promise<T> {
+      if (method === 'POST' && path === '/auth/refresh') {
+        refreshCalls += 1;
+        if (options.hangRefresh) return new Promise<T>(() => {}); // never settles
+        await delay(options.refreshDelayMs ?? 20);
+        const sent = (reqOptions.body as { refreshToken?: string } | undefined)?.refreshToken;
+        if (options.failRefresh || sent !== validRefresh) {
+          // single-use enforcement: a second refresh with the same token is rejected
+          throw ApiError.fromResponse(
+            401,
+            JSON.stringify({ code: 401, name: 'Unauthorized', description: 'refresh token already used' }),
+          );
+        }
+        validRefresh = `refresh-${refreshCalls + 1}`; // rotate: previous token is now burnt
+        validAccess = `access-${refreshCalls}`;
+        return { accessToken: validAccess, refreshToken: validRefresh } as T;
+      }
+      if (reqOptions.token !== validAccess) {
+        throw ApiError.fromResponse(401, 'token expired');
+      }
+      return { path, ok: true } as T;
+    },
+  };
+
+  return {
+    transport,
+    refreshCalls: () => refreshCalls,
+    currentRefreshToken: () => validRefresh,
+  };
+}
+
+function createClient(api: ReturnType<typeof createFakeApi>, refreshTimeoutMs?: number) {
+  const context = createMemoryContext();
+  const auth = new AuthClient(api.transport, context, { refreshTimeoutMs });
+  // Session as left by a login flow, with an access token that has since expired:
+  auth.setTokens({ accessToken: 'expired-access', refreshToken: 'refresh-1' } satisfies TokenPair);
+  return auth;
+}
+
+describe('single-flight token refresh', () => {
+  test('N concurrent 401s trigger exactly ONE refresh call', async () => {
+    const api = createFakeApi();
+    const auth = createClient(api);
+    const N = 8;
+
+    const results = await Promise.all(
+      Array.from({ length: N }, (_, i) => auth.request<{ path: string; ok: boolean }>('GET', `/items/${i}`)),
+    );
+
+    // every request recovered and succeeded after the shared refresh
+    expect(results).toHaveLength(N);
+    results.forEach((result, i) => expect(result).toEqual({ path: `/items/${i}`, ok: true }));
+    // …through exactly one refresh call (single-use token: a second call would have thrown)
+    expect(api.refreshCalls()).toBe(1);
+    // and the rotated pair landed in storage
+    expect(api.currentRefreshToken()).toBe('refresh-2');
+    expect(auth.getAccessToken()).toBe('access-1');
+  });
+
+  test('a 401 refresh rejection clears tokens and rejects ALL waiters', async () => {
+    // failRefresh makes the fake API answer the refresh with a 401 (a real auth rejection:
+    // the refresh token is no longer valid) — the session is genuinely dead, drop it.
+    const api = createFakeApi({ failRefresh: true });
+    const auth = createClient(api);
+
+    const results = await Promise.allSettled([
+      auth.request('GET', '/endpoint1'),
+      auth.request('GET', '/endpoint2'),
+    ]);
+
+    expect(results[0].status).toBe('rejected');
+    expect(results[1].status).toBe('rejected');
+    expect(api.refreshCalls()).toBe(1); // failure was shared, not retried per-waiter
+    expect(auth.getAccessToken()).toBeNull(); // 401 = auth rejection → tokens cleared
+  });
+
+  test('refresh timeout rejects waiters with RefreshTimeout but KEEPS tokens', async () => {
+    // A timeout is a transport failure, not a verdict on the refresh token. Clearing tokens
+    // here would force a logout over a flaky/slow network (JP finding #4) — keep the session
+    // so a later retry can succeed once connectivity returns.
+    const api = createFakeApi({ hangRefresh: true });
+    const auth = createClient(api, 25);
+
+    const results = await Promise.allSettled([
+      auth.request('GET', '/endpoint1'),
+      auth.request('GET', '/endpoint2'),
+    ]);
+
+    for (const result of results) {
+      expect(result.status).toBe('rejected');
+      if (result.status === 'rejected') {
+        expect(result.reason).toBeInstanceOf(ApiError);
+        expect((result.reason as ApiError).errorName).toBe('RefreshTimeout');
+        expect((result.reason as ApiError).statusCode).toBe(408);
+      }
+    }
+    expect(api.refreshCalls()).toBe(1);
+    expect(auth.getAccessToken()).toBe('expired-access'); // transport failure → tokens kept
+  });
+
+  test('a transport failure (network error) rejects waiters but KEEPS tokens', async () => {
+    // The refresh request never reaches the server (offline/DNS/refused): a raw Error, not an
+    // ApiError. Waiters fail, but the session is untouched — no gratuitous forced logout.
+    const transport: HttpTransport = {
+      async request<T>(method: HttpMethod, path: string, reqOptions: RequestOptions = {}): Promise<T> {
+        if (method === 'POST' && path === '/auth/refresh') {
+          throw new TypeError('fetch failed'); // what Node/undici throws when the host is unreachable
+        }
+        if (reqOptions.token !== 'access-0') throw ApiError.fromResponse(401, 'token expired');
+        return { ok: true } as T;
+      },
+    };
+    const context = createMemoryContext();
+    const auth = new AuthClient(transport, context);
+    auth.setTokens({ accessToken: 'expired-access', refreshToken: 'refresh-1' });
+
+    const results = await Promise.allSettled([
+      auth.request('GET', '/endpoint1'),
+      auth.request('GET', '/endpoint2'),
+    ]);
+
+    expect(results[0].status).toBe('rejected');
+    expect(results[1].status).toBe('rejected');
+    expect(auth.getAccessToken()).toBe('expired-access'); // network failure → tokens kept
+  });
+
+  test('a valid access token never triggers a refresh', async () => {
+    const api = createFakeApi();
+    const auth = new AuthClient(api.transport, createMemoryContext());
+    auth.setTokens({ accessToken: 'access-0', refreshToken: 'refresh-1' });
+
+    const result = await auth.request<{ ok: boolean }>('GET', '/me');
+
+    expect(result.ok).toBe(true);
+    expect(api.refreshCalls()).toBe(0);
+  });
+
+  test('non-401 errors propagate untouched, without refreshing', async () => {
+    const transport: HttpTransport = {
+      request: async () => {
+        throw ApiError.fromResponse(
+          409,
+          JSON.stringify({ code: 4090, name: 'Conflict', description: 'already exists' }),
+        );
+      },
+    };
+    const auth = new AuthClient(transport, createMemoryContext());
+    auth.setTokens({ accessToken: 'a', refreshToken: 'r' });
+
+    await expect(auth.request('POST', '/teams', { name: 'x' })).rejects.toMatchObject({
+      statusCode: 409,
+      errorName: 'Conflict',
+      code: 4090,
+    });
+  });
+});

package/templates/packs/ts-sdk/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": []
+  },
+  "include": ["src", "tests", "tsup.config.ts", "vitest.config.ts"]
+}

package/templates/packs/ts-sdk/tsup.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'tsup';
+
+/**
+ * Two entries, matching the exports map:
+ *   "."        → dist/index.{js,cjs,d.ts,d.cts}
+ *   "./types"  → dist/types/index.{js,cjs,d.ts,d.cts}   (types-only subpath)
+ *
+ * All sources are plain .ts — never author .d.ts files in src/ (declaration
+ * generators skip them silently; see docs-architecture/CONVENTIONS_TS.md §1).
+ * scripts/verify-dist.mjs gates the build on the emitted declarations.
+ */
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    'types/index': 'src/types/index.ts',
+  },
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: 'es2022',
+});

package/templates/packs/ts-sdk/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+});

package/templates/packs/vapor-api/CLAUDE.md

@@ -0,0 +1,73 @@
+# {{PROJECT_NAME}} — Claude Code Operating Manual
+
+This project was scaffolded by **AppForge** (pack: vapor-api): a Claude-Code-first
+server-side Swift architecture extracted from production APIs. You (Claude) are the team
+lead AND the primary developer. Follow this manual exactly — it encodes hard-won lessons,
+not preferences.
+
+## Identity
+- Service: **{{PROJECT_NAME}}** · Identifier: `{{BUNDLE_ID}}` · Swift 6 (strict concurrency)
+- Stack: Vapor 4 + Fluent + PostgreSQL (tests run on in-memory SQLite — zero external services)
+- **Deployment target is Linux (Docker).** macOS-green is NOT done — Linux behaves differently
+  (see `GOTCHAS_LINUX_SWIFT.md`).
+
+## Session protocol (MANDATORY)
+1. **Session start**: run the `restore-context` skill — read `.claude/memory/*.md` before doing anything. Never invent project facts.
+2. **Empty project / new idea**: run the `kickoff` skill — it interviews the user, writes the PRD, plans slices, then builds autonomously.
+3. **After significant work**: update `.claude/memory/PROJECT_STATE.md` (and DECISIONS/NEXT_STEPS when relevant) — `save-context` skill.
+
+## Architecture (read the docs before coding)
+The knowledge base lives in `docs-architecture/`. Read the relevant doc BEFORE touching that area:
+
+| You are about to… | Read first |
+|---|---|
+| understand the layer model (stack-agnostic) | `ARCHITECTURE_PRINCIPLES.md` |
+| plan/deliver slices, validate, update memory | `DELIVERY.md` |
+| product spans repos (API + SDK + clients) | `MULTI_REPO_CONTRACT.md` |
+| ship/consume a typed SDK | `SDK_CONTRACT.md` |
+| accept user-supplied URLs (webhooks…) | `SECURITY_USER_URLS.md` |
+| write any documentation | `DOCS_PLACEMENT.md` |
+| add caching/feature flags/auth shortcuts | `ANTI_PATTERNS.md` |
+| add/move any file, create a feature module | `ARCHITECTURE.md` |
+| write any Swift code (errors, env vars, DTOs, registration) | `CONVENTIONS.md` |
+| logging, metrics, Docker, deploy, runtime config | `OPS.md` |
+| HTTP clients, background tasks, migrations, anything Linux | `GOTCHAS_LINUX_SWIFT.md` |
+
+Layer summary (universal contract in ARCHITECTURE_PRINCIPLES.md, Swift mapping in ARCHITECTURE.md):
+L0 `{{PROJECT_NAME}}Foundation` target (pure primitives) · L1 `Monitoring` target (logs/metrics) ·
+L2 feature `Repositories/` + `Migrations/` + external client targets · L3 feature `Services/` + `Entities/`
+(**business logic lives in services, never repositories**) · L5 `Controllers/` + `DTO/` + `Configure/`.
+Imports point downward only; SPM targets enforce the big walls, folders + grep enforce the rest.
+
+## Non-negotiable rules
+- **Typed errors only**: feature code throws `App.Failed.*` cases — never raw `Abort`, never stringly
+  errors. `docs/ERROR_CODES.md` is GENERATED from the enum (`./scripts/generate-error-codes.sh`),
+  never hand-written.
+- **Env discipline**: every environment variable is a case of `AppConfig.Key` (typed, fail-fast at
+  boot) AND a line in `env_dist` AND present in every deploy manifest. `./scripts/validate-env-vars.sh`
+  must pass before any commit that touches config.
+- **ONE HTTP client**: `app.http.client.shared` (AsyncHTTPClient), injected into whatever needs it.
+  `URLSession` is FORBIDDEN — it crashes on Linux (see GOTCHAS_LINUX_SWIFT.md).
+- **Migration order is load-bearing**: new migrations are registered explicitly in `configure.swift`,
+  positioned after every table they reference. Verify on a scratch database, not your incremental dev DB.
+- **Log level comes from the environment** (`--log` flag or `LOG_LEVEL`), never hardcoded. JSON logs
+  in production, text in development — already wired in `entrypoint.swift`.
+- **Never claim done without proof**: `swift test` green + (for endpoints) a curl/test response you
+  actually read. Before shipping: run the test suite inside a Linux container (command in COMMANDS.md).
+- **Memory is law**: contradictions between memory files and code → code wins, then fix the memory file.
+
+## Build commands
+```bash
+swift build                         # compile all targets
+swift test                          # full suite — boots the app on in-memory SQLite
+swift run App serve --hostname 127.0.0.1 --port 8080    # needs .env + PostgreSQL
+curl -s localhost:8080/health       # liveness proof
+
+# Linux gate (the real deployment target) — run before shipping:
+docker run --rm -v "$PWD:/src" -w /src swift:6.2-noble swift test
+```
+More (DB bootstrap, scripts, Docker image) in `.claude/memory/COMMANDS.md`.
+
+## Git
+- Never push without explicit user approval. Feature branches; commit format `add/update/fix(scope) - description`.
+- No AI attribution in commits or file headers.

package/templates/packs/vapor-api/Dockerfile

@@ -0,0 +1,80 @@
+# ================================
+# Build image
+# ================================
+FROM swift:6.2-noble AS build
+
+# OS updates + jemalloc headers (server-grade allocator, linked below)
+RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
+    && apt-get -q update \
+    && apt-get -q dist-upgrade -y \
+    && apt-get install -y libjemalloc-dev
+
+WORKDIR /build
+
+# Resolve dependencies first: this layer is cached and reused as long as
+# Package.swift / Package.resolved do not change.
+COPY ./Package.* ./
+RUN if [ -f ./Package.resolved ]; then \
+        swift package resolve --force-resolved-versions; \
+    else \
+        swift package resolve; \
+    fi
+
+COPY . .
+
+# Release build: static Swift stdlib (no runtime needed in the run image) + jemalloc
+# (measurably lower fragmentation under sustained load than glibc malloc).
+# N.B.: the STATIC jemalloc is incompatible with the static Swift runtime — link dynamic.
+RUN swift build -c release \
+                --static-swift-stdlib \
+                -Xlinker -ljemalloc
+
+WORKDIR /staging
+
+# Main executable
+RUN cp "$(swift build --package-path /build -c release --show-bin-path)/App" ./
+
+# Static backtracer: readable crash reports in production containers.
+RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
+
+# Resources bundled by SPM
+RUN find -L "$(swift build --package-path /build -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
+
+# Public/Resources directories if present — read-only by default.
+RUN [ -d /build/Public ] && { mv /build/Public ./Public && chmod -R a-w ./Public; } || true
+RUN [ -d /build/Resources ] && { mv /build/Resources ./Resources && chmod -R a-w ./Resources; } || true
+
+# ================================
+# Run image
+# ================================
+FROM ubuntu:noble
+
+RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
+    && apt-get -q update \
+    && apt-get -q dist-upgrade -y \
+    && apt-get -q install -y \
+      libjemalloc2 \
+      ca-certificates \
+      tzdata \
+    && rm -r /var/lib/apt/lists/*
+
+# Non-root user — the API never runs as root.
+RUN useradd --user-group --create-home --system --skel /dev/null --home-dir /app vapor
+
+WORKDIR /app
+
+COPY --from=build --chown=vapor:vapor /staging /app
+
+# Crash reporter configuration (pairs with the static backtracer above).
+ENV SWIFT_BACKTRACE=enable=yes,sanitize=yes,threads=all,images=all,interactive=no,swift-backtrace=./swift-backtrace-static
+
+# Log level is RUNTIME configuration — overridable at `docker run`, never hardcoded.
+ARG LOG_LEVEL=info
+ENV LOG_LEVEL=${LOG_LEVEL}
+
+USER vapor:vapor
+
+EXPOSE 8080
+
+ENTRYPOINT ["./App"]
+CMD ["serve", "--env", "production", "--hostname", "0.0.0.0", "--port", "8080"]

package/templates/packs/vapor-api/Package.swift

@@ -0,0 +1,68 @@
+// swift-tools-version:6.0
+import PackageDescription
+
+let swiftSettings: [SwiftSetting] = [
+    .enableUpcomingFeature("ExistentialAny"),
+]
+
+let package = Package(
+    name: "{{PROJECT_NAME}}",
+    platforms: [
+        .macOS(.v13)
+    ],
+    dependencies: [
+        // 💧 Server-side Swift web framework.
+        .package(url: "https://github.com/vapor/vapor.git", from: "4.115.0"),
+        // 🗄 ORM.
+        .package(url: "https://github.com/vapor/fluent.git", from: "4.12.0"),
+        // 🐘 PostgreSQL driver (production database).
+        .package(url: "https://github.com/vapor/fluent-postgres-driver.git", from: "2.10.0"),
+        // 🧪 SQLite driver (in-memory database for the test environment ONLY).
+        .package(url: "https://github.com/vapor/fluent-sqlite-driver.git", from: "4.8.0"),
+        // 📈 Prometheus metrics backend for swift-metrics.
+        .package(url: "https://github.com/swift-server/swift-prometheus.git", from: "2.0.0"),
+    ],
+    targets: [
+        // L0 FOUNDATION — pure Swift primitives. Zero dependencies; builds & tests standalone.
+        .target(
+            name: "{{PROJECT_NAME}}Foundation",
+            swiftSettings: swiftSettings
+        ),
+
+        // L1 OPS — operational plumbing: structured JSON logs, HTTP timing, metrics registry.
+        // Imports the web framework as infrastructure, but NEVER any app code.
+        .target(
+            name: "Monitoring",
+            dependencies: [
+                .product(name: "Vapor", package: "vapor"),
+                .product(name: "Prometheus", package: "swift-prometheus"),
+            ],
+            swiftSettings: swiftSettings
+        ),
+
+        // L2–L5 — feature modules (Entities/Migrations/Repositories/Services/DTO/Controllers),
+        // error contract, configuration and bootstrap. Layering inside this target is
+        // folder-enforced — see docs-architecture/ARCHITECTURE.md.
+        .executableTarget(
+            name: "App",
+            dependencies: [
+                .product(name: "Vapor", package: "vapor"),
+                .product(name: "Fluent", package: "fluent"),
+                .product(name: "FluentPostgresDriver", package: "fluent-postgres-driver"),
+                .product(name: "FluentSQLiteDriver", package: "fluent-sqlite-driver"),
+                .target(name: "{{PROJECT_NAME}}Foundation"),
+                .target(name: "Monitoring"),
+            ],
+            swiftSettings: swiftSettings
+        ),
+
+        .testTarget(
+            name: "AppTests",
+            dependencies: [
+                .target(name: "App"),
+                .product(name: "VaporTesting", package: "vapor"),
+            ],
+            swiftSettings: swiftSettings
+        ),
+    ]
+)

package/templates/packs/vapor-api/Sources/App/App.swift

@@ -0,0 +1,5 @@
+import Foundation
+
+/// Root namespace. Every feature module extends it: `extension App { enum Item { … } }`.
+/// Call sites read as domain language: `App.Item.Service`, `App.Failed.BadRequest`.
+enum App {}

package/templates/packs/vapor-api/Sources/App/Configure/AppConfig.swift

@@ -0,0 +1,108 @@
+import Vapor
+
+/// Typed, fail-fast runtime configuration.
+///
+/// THE rule: every value the app reads from the environment goes through `Key` — never
+/// call `Environment.get` anywhere else. A missing variable kills the boot with a named
+/// error instead of surfacing as a nil three requests later.
+///
+/// Cross-check discipline: each `Key` case must exist in `env_dist` AND in every deploy
+/// manifest (compose files, CI workflows). `scripts/validate-env-vars.sh` enforces it.
+struct AppConfig: Sendable {
+    let databaseHost: String
+    let databasePort: Int
+    let databaseUsername: String
+    let databasePassword: String
+    let databaseName: String
+    let allowedOrigin: String
+    let monitoringEnabled: Bool
+    let metricsToken: String
+
+    static func load(for environment: Environment) -> AppConfig {
+        // `.testing` is EXPLICIT — tests pass it to `Application.make(.testing)`.
+        // Never sniff the test runner from process arguments or env leftovers.
+        guard environment != .testing else { return .testing }
+
+        return AppConfig(
+            databaseHost: Key.DATABASE_HOST.get,
+            databasePort: Key.DATABASE_PORT.getInt,
+            databaseUsername: Key.DATABASE_USERNAME.get,
+            databasePassword: Key.DATABASE_PASSWORD.get,
+            databaseName: Key.DATABASE_NAME.get,
+            allowedOrigin: Key.ALLOWED_ORIGIN.get,
+            monitoringEnabled: Key.MONITORING_ENABLED.getBool,
+            metricsToken: Key.METRICS_TOKEN.get
+        )
+    }
+
+    /// Test fixture — the database values are unused (testing runs on in-memory SQLite),
+    /// monitoring is on so the /metrics contract stays under test.
+    static let testing = AppConfig(
+        databaseHost: "unused-in-testing",
+        databasePort: 0,
+        databaseUsername: "unused-in-testing",
+        databasePassword: "unused-in-testing",
+        databaseName: "unused-in-testing",
+        allowedOrigin: "http://localhost:3000",
+        monitoringEnabled: true,
+        metricsToken: "test-metrics-token"
+    )
+}
+
+extension AppConfig {
+    /// One case per environment variable — `CaseIterable` so the validation script can
+    /// grep this enum and cross-check `env_dist` + deploy manifests.
+    enum Key: String, CaseIterable {
+        case DATABASE_HOST
+        case DATABASE_PORT
+        case DATABASE_USERNAME
+        case DATABASE_PASSWORD
+        case DATABASE_NAME
+        case ALLOWED_ORIGIN
+        case MONITORING_ENABLED
+        case METRICS_TOKEN
+
+        /// Fail fast at boot — a missing variable must kill the process by name.
+        var get: String {
+            guard let value = Environment.get(rawValue) else {
+                fatalError("""
+                Missing environment variable \(rawValue) — add it to .env AND env_dist \
+                AND every deploy manifest, then run scripts/validate-env-vars.sh.
+                """)
+            }
+            return value
+        }
+
+        var getInt: Int {
+            guard let value = Int(get) else {
+                fatalError("Environment variable \(rawValue) must be an integer (got '\(get)')")
+            }
+            return value
+        }
+
+        var getBool: Bool {
+            ["true", "1", "yes"].contains(get.lowercased())
+        }
+    }
+}
+
+// MARK: - Dependency injection via Application.storage
+
+extension AppConfig {
+    struct StorageKey: Vapor.StorageKey {
+        typealias Value = AppConfig
+    }
+}
+
+extension Application {
+    var config: AppConfig {
+        guard let config = storage[AppConfig.StorageKey.self] else {
+            fatalError("AppConfig not loaded — configure(_:) must store it before first use")
+        }
+        return config
+    }
+}
+
+extension Request {
+    var config: AppConfig { application.config }
+}

package/templates/packs/vapor-api/Sources/App/Configure/configure.swift

@@ -0,0 +1,74 @@
+import Fluent
+import FluentPostgresDriver
+import FluentSQLiteDriver
+import Vapor
+import Monitoring
+
+/// Composition root. Order matters: config → database → migrations → middlewares →
+/// monitoring → routes → migrate.
+public func configure(_ app: Application) async throws {
+    let config = AppConfig.load(for: app.environment)
+    app.storage[AppConfig.StorageKey.self] = config
+
+    try databasesInit(app, config: config)
+    migrationsInit(app)
+    middlewaresInit(app, config: config)
+
+    try configureMonitoring(
+        app: app,
+        enabled: config.monitoringEnabled,
+        metricsToken: config.metricsToken
+    )
+
+    try routes(app)
+
+    try await app.autoMigrate()
+}
+
+private func databasesInit(_ app: Application, config: AppConfig) throws {
+    if app.environment == .testing {
+        // In-memory SQLite: tests boot the FULL stack (migrations included) with zero
+        // external services. PostgreSQL-specific behavior still needs a CI job against
+        // a real PostgreSQL before release.
+        app.databases.use(.sqlite(.memory), as: .sqlite)
+    } else {
+        app.databases.use(DatabaseConfigurationFactory.postgres(configuration: .init(
+            hostname: config.databaseHost,
+            port: config.databasePort,
+            username: config.databaseUsername,
+            password: config.databasePassword,
+            database: config.databaseName,
+            tls: .prefer(try .init(configuration: .clientDefault))
+        ), maxConnectionsPerEventLoop: 2, connectionPoolTimeout: .seconds(60)), as: .psql)
+    }
+}
+
+private func migrationsInit(_ app: Application) {
+    // ⚠️ ORDER IS LOAD-BEARING. Fluent runs migrations in registration order; a schema
+    // that references another table (foreign key) must be registered AFTER that table.
+    // New feature → append its register() call here, positioned by its foreign keys,
+    // and verify on a SCRATCH database (docs-architecture/GOTCHAS_LINUX_SWIFT.md).
+    App.Item.Migrations.register(app: app)
+}
+
+private func middlewaresInit(_ app: Application, config: AppConfig) {
+    // Rebuild the stack from scratch: drops Vapor's default RouteLoggingMiddleware,
+    // replaced by HTTPLoggingMiddleware (duration + probe-path exclusion).
+    app.middleware = .init()
+
+    app.middleware.use(CORSMiddleware(configuration: .init(
+        allowedOrigin: .custom(config.allowedOrigin),
+        allowedMethods: [.GET, .POST, .PUT, .PATCH, .DELETE, .OPTIONS],
+        allowedHeaders: [.authorization, .contentType, .accept, .origin, .xRequestedWith],
+        allowCredentials: true,
+        exposedHeaders: [.authorization, .contentType]
+    )))
+
+    app.middleware.use(HTTPLoggingMiddleware())
+
+    // Outer catch-all (Abort + anything untyped)…
+    app.middleware.use(ErrorMiddleware.default(environment: app.environment))
+    // …then the typed-error contract closest to the routes:
+    // CustomError → {code, name, description} JSON (see CONVENTIONS.md).
+    App.Failed.Middlewares.register(app: app)
+}