Merge b8019dfc8c into 352f94612d

fix(packing): multiply item weight by quantity in bag/total weight calcs (#898 )
Quantity now counts toward bag and total weights. Generalised to an itemWeight() helper used by every weight sum (bag totals + max, unassigned, grand total; sidebar + bag modal) with unit tests.
2026-06-23 15:21:46 +00:00 · 2026-05-25 18:02:01 +02:00 · 2026-05-25 17:59:54 +02:00 · 2026-05-25 17:00:58 +02:00 · 2026-05-25 14:29:30 +02:00 · 2026-05-14 17:22:21 +09:00
64 changed files with 6853 additions and 500 deletions
@@ -8,10 +8,33 @@ on:
    branches: [main, dev]
    paths:
      - 'server/**'
-      - '.github/workflows/test.yml'
      - 'client/**'
+      - 'shared/**'
+      - '.github/workflows/test.yml'

 jobs:
+  shared-contracts:
+    name: Shared Contracts (Zod)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: shared/package-lock.json
+
+      - name: Install dependencies
+        run: cd shared && npm ci
+
+      - name: Typecheck
+        run: cd shared && npm run typecheck
+
+      - name: Run tests
+        run: cd shared && npm test
+
  server-tests:
    name: Server Tests
    runs-on: ubuntu-latest
@@ -28,6 +51,15 @@ jobs:
      - name: Install dependencies
        run: cd server && npm ci

+      - name: Build (tsc + tsc-alias -> dist)
+        run: cd server && npm run build
+
+      - name: Typecheck (informational)
+        # Legacy code still has pre-existing type errors; this surfaces them
+        # without blocking the migration. Ratchet to blocking once cleaned up.
+        continue-on-error: true
+        run: cd server && npm run typecheck
+
      - name: Run tests
        run: cd server && npm run test:coverage

@@ -3,6 +3,7 @@ node_modules/

 # Build output
 client/dist/
+server/dist/
 server/public/*
 !server/public/.gitkeep

@@ -6,7 +6,18 @@ RUN npm ci
 COPY client/ ./
 RUN npm run build

-# Stage 2: Production server
+# Stage 2: Build server (TypeScript -> dist via tsc + tsc-alias)
+# --ignore-scripts: tsc only transpiles, so we skip native builds (better-sqlite3)
+# here; the production stage builds the native module.
+FROM node:24-alpine AS server-builder
+WORKDIR /app
+COPY server/package*.json ./
+RUN npm ci --ignore-scripts
+COPY server/ ./
+RUN npm run build
+
+# Stage 3: Production server (runs the compiled JS — NestJS DI needs the
+# decorator metadata that tsc emits; the old tsx runtime did not).
 FROM node:24-alpine

 WORKDIR /app
@@ -19,12 +30,11 @@ RUN apk add --no-cache tzdata dumb-init su-exec python3 make g++ && \
    apk del python3 make g++ && \
    rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx

-COPY server/ ./
+COPY --from=server-builder /app/dist ./dist
 COPY --from=client-builder /app/client/dist ./public
 COPY --from=client-builder /app/client/public/fonts ./public/fonts

-RUN rm -f package-lock.json && \
-    mkdir -p /app/data/logs /app/uploads/files /app/uploads/covers /app/uploads/avatars /app/uploads/photos && \
+RUN mkdir -p /app/data/logs /app/uploads/files /app/uploads/covers /app/uploads/avatars /app/uploads/photos && \
    mkdir -p /app/server && ln -s /app/uploads /app/server/uploads && ln -s /app/data /app/server/data && \
    chown -R node:node /app

@@ -39,4 +49,4 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
  CMD wget -qO- http://localhost:3000/api/health || exit 1

 ENTRYPOINT ["dumb-init", "--"]
-CMD ["sh", "-c", "chown -R node:node /app/data /app/uploads 2>/dev/null || true; exec su-exec node node --import tsx src/index.ts"]
+CMD ["sh", "-c", "chown -R node:node /app/data /app/uploads 2>/dev/null || true; exec su-exec node node dist/index.js"]
@@ -28,6 +28,7 @@
        "remark-breaks": "^4.0.0",
        "remark-gfm": "^4.0.1",
        "topojson-client": "^3.1.0",
+        "zod": "^4.3.6",
        "zustand": "^4.5.2"
      },
      "devDependencies": {
@@ -2153,9 +2154,6 @@
        "arm"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "LGPL-3.0-or-later",
      "optional": true,
      "os": [
@@ -2173,9 +2171,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "LGPL-3.0-or-later",
      "optional": true,
      "os": [
@@ -2193,9 +2188,6 @@
        "s390x"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "LGPL-3.0-or-later",
      "optional": true,
      "os": [
@@ -2211,9 +2203,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "LGPL-3.0-or-later",
      "optional": true,
      "os": [
@@ -2231,9 +2220,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "LGPL-3.0-or-later",
      "optional": true,
      "os": [
@@ -2251,9 +2237,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "LGPL-3.0-or-later",
      "optional": true,
      "os": [
@@ -2271,9 +2254,6 @@
        "arm"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -2297,9 +2277,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -2323,9 +2300,6 @@
        "s390x"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -2347,9 +2321,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -2373,9 +2344,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -2399,9 +2367,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "Apache-2.0",
      "optional": true,
      "os": [
@@ -3160,9 +3125,6 @@
        "arm"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3177,9 +3139,6 @@
        "arm"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3194,9 +3153,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3211,9 +3167,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3228,9 +3181,6 @@
        "loong64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3245,9 +3195,6 @@
        "loong64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3262,9 +3209,6 @@
        "ppc64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3279,9 +3223,6 @@
        "ppc64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3296,9 +3237,6 @@
        "riscv64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3313,9 +3251,6 @@
        "riscv64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3330,9 +3265,6 @@
        "s390x"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3345,9 +3277,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -3362,9 +3291,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -11048,6 +10974,15 @@
      "version": "3.2.1",
      "license": "MIT"
    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
    "node_modules/zustand": {
      "version": "4.5.7",
      "license": "MIT",
@@ -35,6 +35,7 @@
    "remark-breaks": "^4.0.0",
    "remark-gfm": "^4.0.1",
    "topojson-client": "^3.1.0",
+    "zod": "^4.3.6",
    "zustand": "^4.5.2"
  },
  "devDependencies": {
@@ -1,4 +1,5 @@
 import axios, { AxiosInstance } from 'axios'
+import type { WeatherResult } from '@trek/shared'
 import { getSocketId } from './websocket'
 import { isReachable, probeNow } from '../sync/connectivity'
 import en from '../i18n/translations/en'
@@ -501,8 +502,8 @@ export const reservationsApi = {
 }

 export const weatherApi = {
-  get: (lat: number, lng: number, date: string) => apiClient.get('/weather', { params: { lat, lng, date } }).then(r => r.data),
-  getDetailed: (lat: number, lng: number, date: string, lang?: string) => apiClient.get('/weather/detailed', { params: { lat, lng, date, lang } }).then(r => r.data),
+  get: (lat: number, lng: number, date: string): Promise<WeatherResult> => apiClient.get('/weather', { params: { lat, lng, date } }).then(r => r.data),
+  getDetailed: (lat: number, lng: number, date: string, lang?: string): Promise<WeatherResult> => apiClient.get('/weather/detailed', { params: { lat, lng, date, lang } }).then(r => r.data),
 }

 export const configApi = {
@@ -8,7 +8,21 @@ import { useAuthStore } from '../../store/authStore';
 import { useTripStore } from '../../store/tripStore';
 import { resetAllStores, seedStore } from '../../../tests/helpers/store';
 import { buildUser, buildTrip, buildPackingItem } from '../../../tests/helpers/factories';
-import PackingListPanel from './PackingListPanel';
+import PackingListPanel, { itemWeight } from './PackingListPanel';
+
+describe('itemWeight (bag total weight calc)', () => {
+  it('FE-COMP-PACKING-030: multiplies unit weight by quantity', () => {
+    expect(itemWeight({ weight_grams: 120, quantity: 3 })).toBe(360);
+  });
+  it('FE-COMP-PACKING-031: defaults quantity to 1 when missing', () => {
+    expect(itemWeight({ weight_grams: 250 })).toBe(250);
+  });
+  it('FE-COMP-PACKING-032: contributes 0 when weight is missing or zero', () => {
+    expect(itemWeight({ quantity: 5 })).toBe(0);
+    expect(itemWeight({ weight_grams: 0, quantity: 5 })).toBe(0);
+    expect(itemWeight({})).toBe(0);
+  });
+});

 beforeEach(() => {
  resetAllStores();
@@ -69,6 +69,10 @@ function katColor(kat, allCategories) {

 interface PackingBag { id: number; trip_id: number; name: string; color: string; weight_limit_grams: number | null; user_id?: number | null; assigned_username?: string | null }

+/** Weight an item contributes to a total: unit weight times quantity (defaults: 0 g, qty 1). */
+export const itemWeight = (i: { weight_grams?: number | null; quantity?: number | null }): number =>
+  (i.weight_grams || 0) * (i.quantity || 1)
+
 // ── Bag Card ──────────────────────────────────────────────────────────────

 interface BagCardProps {
@@ -1311,8 +1315,8 @@ export default function PackingListPanel({ tripId, items, openImportSignal = 0,

          {bags.map(bag => {
            const bagItems = items.filter(i => i.bag_id === bag.id)
-            const totalWeight = bagItems.reduce((sum, i) => sum + (i.weight_grams || 0), 0)
-            const maxWeight = bag.weight_limit_grams || Math.max(...bags.map(b => items.filter(i => i.bag_id === b.id).reduce((s, i) => s + (i.weight_grams || 0), 0)), 1)
+            const totalWeight = bagItems.reduce((sum, i) => sum + itemWeight(i), 0)
+            const maxWeight = bag.weight_limit_grams || Math.max(...bags.map(b => items.filter(i => i.bag_id === b.id).reduce((s, i) => s + itemWeight(i), 0)), 1)
            const pct = Math.min(100, Math.round((totalWeight / maxWeight) * 100))
            return (
              <BagCard key={bag.id} bag={bag} bagItems={bagItems} totalWeight={totalWeight} pct={pct} tripId={tripId} tripMembers={tripMembers} canEdit={canEdit} onDelete={() => handleDeleteBag(bag.id)} onUpdate={handleUpdateBag} onSetMembers={handleSetBagMembers} t={t} compact />
@@ -1322,7 +1326,7 @@ export default function PackingListPanel({ tripId, items, openImportSignal = 0,
          {/* Unassigned */}
          {(() => {
            const unassigned = items.filter(i => !i.bag_id)
-            const unassignedWeight = unassigned.reduce((s, i) => s + (i.weight_grams || 0), 0)
+            const unassignedWeight = unassigned.reduce((s, i) => s + itemWeight(i), 0)
            if (unassigned.length === 0) return null
            return (
              <div style={{ marginBottom: 14, opacity: 0.6 }}>
@@ -1342,7 +1346,7 @@ export default function PackingListPanel({ tripId, items, openImportSignal = 0,
          <div style={{ borderTop: '1px solid var(--border-secondary)', paddingTop: 10, marginTop: 6 }}>
            <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: 12, fontWeight: 700, color: 'var(--text-primary)' }}>
              <span>{t('packing.totalWeight')}</span>
-              <span>{(() => { const w = items.reduce((s, i) => s + (i.weight_grams || 0), 0); return w >= 1000 ? `${(w / 1000).toFixed(1)} kg` : `${w} g` })()}</span>
+              <span>{(() => { const w = items.reduce((s, i) => s + itemWeight(i), 0); return w >= 1000 ? `${(w / 1000).toFixed(1)} kg` : `${w} g` })()}</span>
            </div>
          </div>

@@ -1380,8 +1384,8 @@ export default function PackingListPanel({ tripId, items, openImportSignal = 0,

            {bags.map(bag => {
              const bagItems = items.filter(i => i.bag_id === bag.id)
-              const totalWeight = bagItems.reduce((sum, i) => sum + (i.weight_grams || 0), 0)
-              const maxWeight = Math.max(...bags.map(b => items.filter(i => i.bag_id === b.id).reduce((s, i) => s + (i.weight_grams || 0), 0)), 1)
+              const totalWeight = bagItems.reduce((sum, i) => sum + itemWeight(i), 0)
+              const maxWeight = Math.max(...bags.map(b => items.filter(i => i.bag_id === b.id).reduce((s, i) => s + itemWeight(i), 0)), 1)
              const pct = Math.min(100, Math.round((totalWeight / maxWeight) * 100))
              return (
                <BagCard key={bag.id} bag={bag} bagItems={bagItems} totalWeight={totalWeight} pct={pct} tripId={tripId} tripMembers={tripMembers} canEdit={canEdit} onDelete={() => handleDeleteBag(bag.id)} onUpdate={handleUpdateBag} onSetMembers={handleSetBagMembers} t={t} />
@@ -1391,7 +1395,7 @@ export default function PackingListPanel({ tripId, items, openImportSignal = 0,
            {/* Unassigned */}
            {(() => {
              const unassigned = items.filter(i => !i.bag_id)
-              const unassignedWeight = unassigned.reduce((s, i) => s + (i.weight_grams || 0), 0)
+              const unassignedWeight = unassigned.reduce((s, i) => s + itemWeight(i), 0)
              if (unassigned.length === 0) return null
              return (
                <div style={{ marginBottom: 16, opacity: 0.6 }}>
@@ -1411,7 +1415,7 @@ export default function PackingListPanel({ tripId, items, openImportSignal = 0,
            <div style={{ borderTop: '1px solid var(--border-secondary)', paddingTop: 12, marginTop: 8 }}>
              <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: 14, fontWeight: 700, color: 'var(--text-primary)' }}>
                <span>{t('packing.totalWeight')}</span>
-                <span>{(() => { const w = items.reduce((s, i) => s + (i.weight_grams || 0), 0); return w >= 1000 ? `${(w / 1000).toFixed(1)} kg` : `${w} g` })()}</span>
+                <span>{(() => { const w = items.reduce((s, i) => s + itemWeight(i), 0); return w >= 1000 ? `${(w / 1000).toFixed(1)} kg` : `${w} g` })()}</span>
              </div>
            </div>

@@ -15,6 +15,7 @@ import ar from './translations/ar'
 import br from './translations/br'
 import cs from './translations/cs'
 import pl from './translations/pl'
+import ja from './translations/ja'
 import { SUPPORTED_LANGUAGES, SupportedLanguageCode } from './supportedLanguages'

 export { SUPPORTED_LANGUAGES }
@@ -23,7 +24,7 @@ type TranslationStrings = Record<string, string | { name: string; category: stri

 // Keyed by SupportedLanguageCode so TypeScript enforces all languages have a translation.
 const translations: Record<SupportedLanguageCode, TranslationStrings> = {
-  de, en, es, fr, hu, it, ru, zh, 'zh-TW': zhTw, nl, id, ar, br, cs, pl,
+  de, en, es, fr, hu, it, ru, zh, 'zh-TW': zhTw, nl, id, ar, br, cs, pl, ja,
 }

 // Derived from SUPPORTED_LANGUAGES — add new languages there, not here.
@@ -38,7 +39,7 @@ export function getLocaleForLanguage(language: string): string {

 export function getIntlLanguage(language: string): string {
  if (language === 'br') return 'pt-BR'
-  return ['de', 'es', 'fr', 'hu', 'it', 'ru', 'zh', 'zh-TW', 'nl', 'ar', 'cs', 'pl', 'id'].includes(language) ? language : 'en'
+  return ['de', 'es', 'fr', 'hu', 'it', 'ru', 'zh', 'zh-TW', 'nl', 'ar', 'cs', 'pl', 'id', 'ja' ].includes(language) ? language : 'en'
 }

 export function isRtlLanguage(language: string): boolean {
@@ -12,8 +12,9 @@ export const SUPPORTED_LANGUAGES = [
  { value: 'zh',    label: '简体中文',              locale: 'zh-CN' },
  { value: 'zh-TW', label: '繁體中文',              locale: 'zh-TW' },
  { value: 'it',    label: 'Italiano',             locale: 'it-IT' },
-  { value: 'ar',    label: 'العربية',              locale: 'ar-SA' },
+  { value: 'ar',    label: 'العربية',                 locale: 'ar-SA' },
  { value: 'id',    label: 'Bahasa Indonesia',     locale: 'id-ID' },
+  { value: 'ja',    label: '日本語',                locale: 'ja-JP' },
 ] as const

 export type SupportedLanguageCode = typeof SUPPORTED_LANGUAGES[number]['value']
@@ -91,7 +91,7 @@ describe('isRtlLanguage', () => {
 describe('SUPPORTED_LANGUAGES', () => {
  it('FE-COMP-I18N-009: contains expected entries with value/label shape', () => {
    expect(Array.isArray(SUPPORTED_LANGUAGES)).toBe(true)
-    expect(SUPPORTED_LANGUAGES).toHaveLength(15)
+    expect(SUPPORTED_LANGUAGES).toHaveLength(16)
    expect(SUPPORTED_LANGUAGES).toContainEqual(expect.objectContaining({ value: 'en', label: 'English' }))
    expect(SUPPORTED_LANGUAGES).toContainEqual(expect.objectContaining({ value: 'ar', label: 'العربية' }))
  })
@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+// Smoke test: proves the client toolchain (vite / vitest) resolves @trek/shared.
+import { idParamSchema, paginationQuerySchema } from '@trek/shared';
+
+describe('@trek/shared resolves in the client toolchain', () => {
+  it('imports and uses a shared schema', () => {
+    expect(idParamSchema.parse('7')).toBe(7);
+    expect(paginationQuerySchema.parse({})).toEqual({ page: 1, perPage: 50 });
+  });
+});
@@ -7,6 +7,11 @@
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
+    "baseUrl": ".",
+    "paths": {
+      "@trek/shared": ["../shared/src/index.ts"],
+      "@trek/shared/*": ["../shared/src/*"]
+    },
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,
@@ -1,6 +1,7 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import { VitePWA } from 'vite-plugin-pwa'
+import { fileURLToPath } from 'node:url'

 export default defineConfig({
  plugins: [
@@ -88,6 +89,15 @@ export default defineConfig({
      },
    }),
  ],
+  resolve: {
+    alias: {
+      // @trek/shared — Zod contract package (dev: resolved to TS source).
+      '@trek/shared': fileURLToPath(new URL('../shared/src/index.ts', import.meta.url)),
+    },
+    // @trek/shared imports zod from its own source; it lives outside this root,
+    // so pin zod to the client's copy (one instance, resolvable from anywhere).
+    dedupe: ['zod'],
+  },
  build: {
    sourcemap: false,
    modulePreload: { polyfill: true },
@@ -1,8 +1,19 @@
 import { defineConfig } from 'vitest/config';
 import react from '@vitejs/plugin-react';
+import { fileURLToPath } from 'node:url';

 export default defineConfig({
  plugins: [react()],
+  resolve: {
+    alias: {
+      // @trek/shared — Zod contract package (tests resolve it to TS source,
+      // mirroring the alias in vite.config.js used by the dev server / build).
+      '@trek/shared': fileURLToPath(new URL('../shared/src/index.ts', import.meta.url)),
+    },
+    // Mirror vite.config.js: keep a single zod instance resolvable from the
+    // shared source, which lives outside this project root.
+    dedupe: ['zod'],
+  },
  test: {
    root: '.',
    globals: true,
@@ -3,17 +3,25 @@
  "version": "3.0.22",
  "main": "src/index.ts",
  "scripts": {
-    "start": "node --import tsx src/index.ts",
-    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "dev": "node scripts/dev.mjs",
+    "build": "node scripts/build.mjs",
+    "start:prod": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:unit": "vitest run tests/unit",
    "test:integration": "vitest run tests/integration",
    "test:ws": "vitest run tests/websocket",
+    "test:parity": "vitest run tests/parity",
+    "test:e2e": "vitest run tests/e2e",
    "test:coverage": "vitest run --coverage"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@nestjs/common": "^11.1.24",
+    "@nestjs/core": "^11.1.24",
+    "@nestjs/platform-express": "^11.1.24",
    "archiver": "^6.0.1",
    "bcryptjs": "^2.4.3",
    "better-sqlite3": "^12.8.0",
@@ -30,22 +38,30 @@
    "nodemailer": "^8.0.5",
    "otplib": "^12.0.1",
    "qrcode": "^1.5.4",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
    "semver": "^7.7.4",
    "tsx": "^4.21.0",
    "typescript": "^6.0.2",
    "undici": "^7.0.0",
    "unzipper": "^0.12.3",
    "uuid": "^14.0.0",
-    "ws": "^8.19.0",
+    "ws": "^8.21.0",
    "zod": "^4.3.6"
  },
  "overrides": {
    "hono": "^4.12.16",
    "@hono/node-server": "^1.19.13",
    "picomatch": "^4.0.4",
-    "ip-address": "^10.1.1"
+    "ip-address": "^10.1.1",
+    "multer": "^2.1.1",
+    "ws": "^8.21.0",
+    "qs": "^6.15.2",
+    "file-type": "^21.3.4"
  },
  "devDependencies": {
+    "@nestjs/testing": "^11.1.24",
+    "@swc/core": "^1.15.40",
    "@types/archiver": "^7.0.0",
    "@types/bcryptjs": "^2.4.6",
    "@types/better-sqlite3": "^7.6.13",
@@ -66,7 +82,9 @@
    "@vitest/coverage-v8": "^3.2.4",
    "nodemon": "^3.1.0",
    "supertest": "^7.2.2",
+    "tsc-alias": "^1.8.17",
    "tz-lookup": "^6.1.25",
+    "unplugin-swc": "^1.5.9",
    "vitest": "^3.2.4"
  }
 }
@@ -0,0 +1,14 @@
+import { execSync } from 'node:child_process';
+
+// tsc emits JS even with type errors (noEmitOnError:false), but still exits
+// non-zero to report them. We must run tsc-alias regardless, so run tsc in a
+// try/catch and always proceed to the path-rewrite step.
+// Type correctness is enforced separately via `npm run typecheck`.
+try {
+  execSync('tsc -p tsconfig.build.json', { stdio: 'inherit' });
+} catch {
+  console.warn('[build] tsc reported type errors — emitting anyway (gated by `npm run typecheck`).');
+}
+
+execSync('tsc-alias -p tsconfig.build.json', { stdio: 'inherit' });
+console.log('[build] dist ready (path aliases rewritten).');
@@ -0,0 +1,22 @@
+import { execSync, spawn } from 'node:child_process';
+
+// Dev runtime for the co-hosted NestJS + legacy Express server.
+// NestJS DI needs decorator metadata, which the old tsx/esbuild runtime does not
+// emit — so dev runs the tsc build with watchers (same toolchain as prod `dist`).
+// Initial build first so `node --watch dist/index.js` has something to start.
+console.log('[dev] initial build...');
+execSync('node scripts/build.mjs', { stdio: 'inherit' });
+
+const watchers = [
+  ['npx', ['tsc', '-w', '-p', 'tsconfig.build.json', '--preserveWatchOutput']],
+  ['npx', ['tsc-alias', '-w', '-p', 'tsconfig.build.json']],
+  ['node', ['--watch', 'dist/index.js']],
+];
+
+const children = watchers.map(([cmd, args]) =>
+  spawn(cmd, args, { stdio: 'inherit', shell: true }),
+);
+
+const stop = () => { children.forEach((c) => { try { c.kill(); } catch {} }); process.exit(0); };
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);
@@ -26,7 +26,6 @@ import airportsRoutes from './routes/airports';
 import filesRoutes from './routes/files';
 import reservationsRoutes from './routes/reservations';
 import dayNotesRoutes from './routes/dayNotes';
-import weatherRoutes from './routes/weather';
 import settingsRoutes from './routes/settings';
 import budgetRoutes from './routes/budget';
 import collabRoutes from './routes/collab';
@@ -361,7 +360,8 @@ export function createApp(): express.Application {
  app.use('/api/photos', photoRoutes);
  app.use('/api/maps', mapsRoutes);
  app.use('/api/airports', airportsRoutes);
-  app.use('/api/weather', weatherRoutes);
+  // /api/weather is served by the NestJS weather module (see src/nest/weather);
+  // the legacy Express route was decommissioned after the migration (L1).
  app.use('/api/settings', settingsRoutes);
  app.use('/api/system-notices', systemNoticesRoutes);
  app.use('/api/backup', backupRoutes);
@@ -1,7 +1,16 @@
+import 'reflect-metadata';
 import 'dotenv/config';
 import path from 'node:path';
 import fs from 'node:fs';
+import http from 'node:http';
+import express from 'express';
+import cookieParser from 'cookie-parser';
+import { NestFactory } from '@nestjs/core';
+import { ExpressAdapter } from '@nestjs/platform-express';
+import type { INestApplication } from '@nestjs/common';
 import { createApp } from './app';
+import { AppModule } from './nest/app.module';
+import { getNestPrefixes, makeNestPathMatcher } from './nest/strangler';

 // Create upload and data directories on startup
 const uploadsDir = path.join(__dirname, '../uploads');
@@ -16,7 +25,10 @@ const tmpDir = path.join(__dirname, '../data/tmp');
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 });

-const app = createApp();
+// Legacy Express app — unchanged. NestJS (its own Express 5 instance) is mounted
+// in front of it (strangler pattern): migrated route prefixes are served by Nest,
+// everything else falls through to this app via a fallback middleware.
+const legacyApp = createApp();

 import * as scheduler from './scheduler';
 import { getAppUrl, getMcpSafeUrl } from './services/notifications';
@@ -49,6 +61,11 @@ const onListen = () => {
    '──────────────────────────────────────',
  ];
  banner.forEach(l => console.log(l));
+  sLogInfo(
+    NEST_PREFIXES.length
+      ? `NestJS handling prefixes: ${NEST_PREFIXES.join(', ')} (override via NEST_PREFIXES)`
+      : 'NestJS prefixes: none — all routes served by the legacy Express app',
+  );
  if (process.env.APP_URL) {
    let parsedAppUrl: URL | null = null;
    try { parsedAppUrl = new URL(process.env.APP_URL); } catch { /* invalid */ }
@@ -84,9 +101,42 @@ const onListen = () => {
  });
 };

-const server = HOST
-  ? app.listen(PORT, HOST, onListen)
-  : app.listen(PORT, onListen);
+let server: http.Server;
+let nestApp: INestApplication;
+
+// Strangler toggle: prefixes served by Nest (env-overridable, instant rollback).
+const NEST_PREFIXES = getNestPrefixes();
+const isNestPath = makeNestPathMatcher(NEST_PREFIXES);
+
+async function bootstrap(): Promise<void> {
+  // Nest runs on its own Express instance (bodyParser off so request bodies reach
+  // the legacy app untouched — it has its own parsers; /mcp relies on raw body).
+  // Nest body parsing is safe here: the dispatcher only forwards migrated
+  // prefixes to this instance, so the legacy app (and raw-body routes like /mcp)
+  // is reached separately and never passes through Nest's parser.
+  nestApp = await NestFactory.create(AppModule, new ExpressAdapter());
+  // cookie-parser so the auth guard can read the existing `trek_session` cookie.
+  nestApp.use(cookieParser());
+  // (TrekExceptionFilter is registered globally via APP_FILTER in AppModule.)
+  await nestApp.init();
+  const nestInstance = nestApp.getHttpAdapter().getInstance();
+
+  // Top-level dispatcher: migrated prefixes -> Nest, everything else -> legacy
+  // Express (unchanged). Nest never sees non-migrated paths, so its 404 handler
+  // only applies within migrated prefixes.
+  const top = express();
+  top.use((req, res, next) => (isNestPath(req.path) ? nestInstance(req, res, next) : next()));
+  top.use(legacyApp);
+
+  server = http.createServer(top);
+  if (HOST) server.listen(PORT, HOST, onListen);
+  else server.listen(PORT, onListen);
+}
+
+bootstrap().catch((err) => {
+  console.error('Fatal: failed to bootstrap server', err);
+  process.exit(1);
+});

 // Graceful shutdown
 function shutdown(signal: string): void {
@@ -95,6 +145,7 @@ function shutdown(signal: string): void {
  sLogInfo(`${signal} received — shutting down gracefully...`);
  scheduler.stop();
  closeMcpSessions();
+  void nestApp?.close();
  server.close(() => {
    sLogInfo('HTTP server closed');
    const { closeDb } = require('./db/database');
@@ -111,4 +162,4 @@ function shutdown(signal: string): void {
 process.on('SIGTERM', () => shutdown('SIGTERM'));
 process.on('SIGINT', () => shutdown('SIGINT'));

-export default app;
+export default legacyApp;
@@ -0,0 +1,58 @@
+# NestJS migration layer — module & test guide
+
+This folder holds the co-hosted NestJS app that incrementally strangles the legacy
+Express API (see the "Brownfield Rewrite" board). Until a prefix is migrated, the
+top-level dispatcher in `src/index.ts` routes it to the legacy app; migrated
+prefixes go to Nest. **Weather (`weather/`) is the reference implementation** — copy
+its shape when migrating a new domain.
+
+## Module layout (per domain)
+
+```
+shared/src/<domain>/<domain>.schema.ts(.spec.ts)   # Zod contract — single source of truth
+server/src/nest/<domain>/<domain>.service.ts        # business logic (ported 1:1 from the Express service)
+server/src/nest/<domain>/<domain>.controller.ts     # same routes/verbs/params/status codes as Express
+server/src/nest/<domain>/<domain>.module.ts         # registered in app.module.ts
+```
+
+Add the prefix to `DEFAULT_NEST_PREFIXES` in `strangler.ts` to route it to Nest
+(operators can override at runtime via the `NEST_PREFIXES` env var — instant
+rollback, no redeploy).
+
+## Parity is law
+
+A migrated route must be **byte-identical** for the client: same URL, method,
+query/body, HTTP status, `Set-Cookie`, and JSON body — including bespoke error
+strings. Where the legacy route returns a hand-written error (e.g. weather's
+`{ error: 'Latitude and longitude are required' }`), reproduce that exact body in
+the controller rather than relying on the generic `ZodValidationPipe` envelope.
+
+## How to write the tests
+
+Every module ships three kinds of tests; the coverage gate (`vitest.config.ts`,
+scoped to `src/nest/**`) requires ≥80%.
+
+1. **Service / controller unit spec** — `tests/unit/nest/<domain>.controller.test.ts`.
+   Instantiate the controller with a mocked service; assert status codes, the exact
+   `{ error }` bodies, and that inputs are forwarded correctly (defaults, coercion).
+   See `weather.controller.test.ts`.
+
+2. **Parity test** — `tests/parity/<domain>.parity.test.ts`. Mock the shared service
+   identically for both apps, then fire the same request at the Express route and the
+   Nest controller with the `expectParity()` harness (`tests/parity/parity.ts`) and
+   assert identical status + body. This is the gate before flipping the toggle.
+   See `weather.parity.test.ts`.
+
+3. **e2e** — `tests/e2e/<domain>.e2e.test.ts`. Boot the Nest module against a temp
+   in-memory SQLite db via the shared harness (`tests/e2e/harness.ts`:
+   `createTempDb`/`seedUser`/`sessionCookie`), exercising the **real** `JwtAuthGuard`
+   end-to-end (401 without cookie, 200 with a signed session). Mock external I/O
+   (HTTP/etc.). See `weather.e2e.test.ts`.
+
+## Definition of Done (per module)
+
+Contract in `@trek/shared` → service ported 1:1 → controller with identical routes →
+validation/error parity → unit + parity + e2e tests over the gate → prefix toggled to
+Nest → parity verified on the demo DB → **then** decommission the old Express
+route/service (separate step, after the toggle is confirmed in prod) → frontend points
+at the typed contract (Frontend Track).
@@ -0,0 +1,23 @@
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+import { DatabaseModule } from './database/database.module';
+import { HealthController } from './health/health.controller';
+import { HealthService } from './health/health.service';
+import { WeatherModule } from './weather/weather.module';
+import { TrekExceptionFilter } from './common/trek-exception.filter';
+
+/**
+ * Root NestJS module for the incremental migration. Domain modules
+ * (weather, notifications, ...) get registered here as they are migrated.
+ */
+@Module({
+  imports: [DatabaseModule, WeatherModule],
+  controllers: [HealthController],
+  providers: [
+    HealthService,
+    // Global error-envelope normaliser (DI-registered so it also catches
+    // framework-level exceptions like the not-found handler).
+    { provide: APP_FILTER, useClass: TrekExceptionFilter },
+  ],
+})
+export class AppModule {}
@@ -0,0 +1,19 @@
+import { CanActivate, ExecutionContext, HttpException, Injectable } from '@nestjs/common';
+import type { Request } from 'express';
+import type { User } from '../../types';
+
+/**
+ * Mirrors the legacy `adminOnly` middleware: requires an authenticated admin.
+ * Use together with JwtAuthGuard (which populates req.user):
+ * `@UseGuards(JwtAuthGuard, AdminGuard)`.
+ */
+@Injectable()
+export class AdminGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request & { user?: User }>();
+    if (!req.user || req.user.role !== 'admin') {
+      throw new HttpException({ error: 'Admin access required' }, 403);
+    }
+    return true;
+  }
+}
@@ -0,0 +1,12 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import type { User } from '../../types';
+
+/**
+ * Resolves the authenticated user attached by JwtAuthGuard.
+ * Use on guarded handlers: `getThing(@CurrentUser() user: User) { ... }`.
+ */
+export const CurrentUser = createParamDecorator(
+  (_data: unknown, context: ExecutionContext): User | undefined => {
+    return context.switchToHttp().getRequest().user;
+  },
+);
@@ -0,0 +1,28 @@
+import { CanActivate, ExecutionContext, HttpException, Injectable } from '@nestjs/common';
+import type { Request } from 'express';
+import { extractToken, verifyJwtAndLoadUser } from '../../middleware/auth';
+
+/**
+ * Validates TREK's existing JWT session — the same httpOnly `trek_session`
+ * cookie (or `Authorization: Bearer`) the legacy app uses. Reuses the canonical
+ * `verifyJwtAndLoadUser` so the secret, the password_version invalidation gate
+ * and the loaded user are IDENTICAL to the Express middleware. No new tokens.
+ *
+ * Error bodies match the legacy 401 shape exactly so the client is unaffected.
+ */
+@Injectable()
+export class JwtAuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request>();
+    const token = extractToken(req);
+    if (!token) {
+      throw new HttpException({ error: 'Access token required', code: 'AUTH_REQUIRED' }, 401);
+    }
+    const user = verifyJwtAndLoadUser(token);
+    if (!user) {
+      throw new HttpException({ error: 'Invalid or expired token', code: 'AUTH_REQUIRED' }, 401);
+    }
+    (req as Request & { user?: unknown }).user = user;
+    return true;
+  }
+}
@@ -0,0 +1,42 @@
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
+import type { Response } from 'express';
+
+/**
+ * Normalises every Nest exception to TREK's legacy error envelope so migrated
+ * routes are byte-identical for the client:
+ *   - 4xx -> { error: <message> }   (5xx -> { error: 'Internal server error' })
+ *   - exceptions already throwing { error, code? } (e.g. the auth guards) pass through
+ * This replaces Nest's default { statusCode, message, error } body, which the
+ * TREK client does not expect.
+ */
+@Catch()
+export class TrekExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const res = host.switchToHttp().getResponse<Response>();
+
+    if (exception instanceof HttpException) {
+      const status = exception.getStatus();
+      const body = exception.getResponse();
+
+      // Already in TREK shape (e.g. guards throw { error, code }): pass through.
+      if (body && typeof body === 'object' && 'error' in (body as Record<string, unknown>)) {
+        res.status(status).json(body);
+        return;
+      }
+
+      const raw = typeof body === 'string' ? body : (body as { message?: unknown })?.message;
+      const message =
+        status < 500
+          ? Array.isArray(raw)
+            ? raw.join(', ')
+            : String(raw ?? 'Error')
+          : 'Internal server error';
+      res.status(status).json({ error: message });
+      return;
+    }
+
+    // Unknown/unhandled error — mirror the legacy 500 behaviour.
+    console.error('Unhandled error:', exception);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+}
@@ -0,0 +1,26 @@
+import { ArgumentMetadata, HttpException, Injectable, PipeTransform } from '@nestjs/common';
+import type { ZodType } from 'zod';
+
+/**
+ * Validates an incoming @Body()/@Query() against a Zod schema (from @trek/shared)
+ * and returns the parsed, typed value. On failure it throws TREK's error envelope
+ * `{ error: string }` with status 400 — the same shape the legacy routes produce,
+ * so the client's error handling is unaffected.
+ *
+ * Usage: `@Body(new ZodValidationPipe(someSchema)) dto: Dto`.
+ */
+@Injectable()
+export class ZodValidationPipe implements PipeTransform {
+  constructor(private readonly schema: ZodType) {}
+
+  transform(value: unknown, _metadata: ArgumentMetadata): unknown {
+    const result = this.schema.safeParse(value);
+    if (!result.success) {
+      const message = result.error.issues
+        .map((i) => `${i.path.join('.') || 'body'}: ${i.message}`)
+        .join('; ');
+      throw new HttpException({ error: message }, 400);
+    }
+    return result.data;
+  }
+}
@@ -0,0 +1,13 @@
+import { Global, Module } from '@nestjs/common';
+import { DatabaseService } from './database.service';
+
+/**
+ * Global so every migrated module can inject DatabaseService without re-importing.
+ * Wraps the existing better-sqlite3 singleton (no new connection).
+ */
+@Global()
+@Module({
+  providers: [DatabaseService],
+  exports: [DatabaseService],
+})
+export class DatabaseModule {}
@@ -0,0 +1,39 @@
+import { Injectable } from '@nestjs/common';
+import type Database from 'better-sqlite3';
+import { db } from '../../db/database';
+
+/**
+ * Injectable wrapper around TREK's existing better-sqlite3 connection.
+ *
+ * `db` is a Proxy onto the singleton connection the legacy app already uses
+ * (WAL enabled), so Nest modules share the exact same connection — no second
+ * connection, no split state, single writer preserved.
+ */
+@Injectable()
+export class DatabaseService {
+  /** The shared better-sqlite3 connection (same singleton the legacy app uses). */
+  get connection(): Database.Database {
+    return db;
+  }
+
+  prepare(sql: string): Database.Statement {
+    return db.prepare(sql);
+  }
+
+  get<T = unknown>(sql: string, ...params: unknown[]): T | undefined {
+    return db.prepare(sql).get(...params) as T | undefined;
+  }
+
+  all<T = unknown>(sql: string, ...params: unknown[]): T[] {
+    return db.prepare(sql).all(...params) as T[];
+  }
+
+  run(sql: string, ...params: unknown[]): Database.RunResult {
+    return db.prepare(sql).run(...params);
+  }
+
+  /** Run `fn` inside a synchronous better-sqlite3 transaction. */
+  transaction<T>(fn: (conn: Database.Database) => T): T {
+    return db.transaction(() => fn(db))();
+  }
+}
@@ -0,0 +1,41 @@
+import { Body, Controller, Get, Post, UseGuards } from '@nestjs/common';
+import { z } from 'zod';
+import type { User } from '../../types';
+import { HealthService } from './health.service';
+import { JwtAuthGuard } from '../auth/jwt-auth.guard';
+import { CurrentUser } from '../auth/current-user.decorator';
+import { ZodValidationPipe } from '../common/zod-validation.pipe';
+
+// Local demo schema (real domains import their schema from @trek/shared).
+const echoSchema = z.object({ name: z.string().min(1) });
+
+/**
+ * Foundation smoke endpoints for the co-hosted NestJS app.
+ * Proves: boot, routing, type-based DI, the shared SQLite connection, the
+ * JWT-cookie auth guard, and the Zod validation pipe + error-envelope parity.
+ *
+ * Lives under /api/_nest/* so it never collides with the legacy Express API.
+ */
+@Controller('api/_nest')
+export class HealthController {
+  constructor(private readonly healthService: HealthService) {}
+
+  @Get('health')
+  getHealth() {
+    return { ok: true, ...this.healthService.info() };
+  }
+
+  /** Guarded: returns the authenticated user, proving JwtAuthGuard + @CurrentUser. */
+  @Get('me')
+  @UseGuards(JwtAuthGuard)
+  me(@CurrentUser() user: User) {
+    return user;
+  }
+
+  /** Validated: proves the Zod pipe (400 + { error } on failure) and body parsing. */
+  @Post('echo')
+  @UseGuards(JwtAuthGuard)
+  echo(@Body(new ZodValidationPipe(echoSchema)) body: z.infer<typeof echoSchema>) {
+    return { youSent: body };
+  }
+}
@@ -0,0 +1,21 @@
+import { Injectable } from '@nestjs/common';
+import { DatabaseService } from '../database/database.service';
+
+/**
+ * Smoke service proving NestJS DI works under the chosen runtime AND that the
+ * injected DatabaseService talks to TREK's existing SQLite connection.
+ */
+@Injectable()
+export class HealthService {
+  constructor(private readonly database: DatabaseService) {}
+
+  info() {
+    const row = this.database.get<{ n: number }>('SELECT COUNT(*) AS n FROM users');
+    return {
+      runtime: 'nestjs',
+      diInjected: true,
+      // Proof the shared connection works: real row count from the existing DB.
+      userCount: row?.n ?? null,
+    };
+  }
+}
@@ -0,0 +1,24 @@
+/**
+ * Strangler toggle for the incremental NestJS migration.
+ *
+ * `getNestPrefixes()` returns the request path prefixes that NestJS handles;
+ * every other path falls through to the legacy Express app. The default is the
+ * set of prefixes whose Nest modules exist. Operators can override it at runtime
+ * via the `NEST_PREFIXES` env var (comma-separated) for instant Nest<->Express
+ * rollback — no redeploy, no code change. Setting `NEST_PREFIXES=` (empty) routes
+ * everything back to the legacy app.
+ */
+const DEFAULT_NEST_PREFIXES = ['/api/_nest', '/api/weather'];
+
+export function getNestPrefixes(): string[] {
+  const raw = process.env.NEST_PREFIXES;
+  if (raw !== undefined) {
+    return raw.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return DEFAULT_NEST_PREFIXES;
+}
+
+/** Builds a matcher: true when `path` belongs to one of the migrated prefixes. */
+export function makeNestPathMatcher(prefixes: string[]): (path: string) => boolean {
+  return (path) => prefixes.some((prefix) => path === prefix || path.startsWith(prefix + '/'));
+}
@@ -0,0 +1,66 @@
+import { Controller, Get, HttpException, Query, UseGuards } from '@nestjs/common';
+import type { WeatherResult } from '@trek/shared';
+import { WeatherService } from './weather.service';
+import { JwtAuthGuard } from '../auth/jwt-auth.guard';
+import { ApiError } from '../../services/weatherService';
+
+/**
+ * /api/weather — first migrated leaf module (the pilot).
+ *
+ * Behaviour is byte-identical to the legacy Express route (server/src/routes/
+ * weather.ts): same paths, query params, status codes and `{ error }` bodies.
+ *
+ * Parity note: the "X is required" 400s and the 500 fallback messages are bespoke
+ * strings, not the generic Zod-pipe envelope, so they are reproduced here exactly
+ * rather than derived from the schema. The Zod contract/types live in
+ * @trek/shared/weather and are used for typing; `lang` defaults to 'de' only when
+ * the param is absent, matching the Express destructuring default.
+ */
+@Controller('api/weather')
+@UseGuards(JwtAuthGuard)
+export class WeatherController {
+  constructor(private readonly weather: WeatherService) {}
+
+  @Get()
+  async getWeather(
+    @Query('lat') lat?: string,
+    @Query('lng') lng?: string,
+    @Query('date') date?: string,
+    @Query('lang') lang?: string,
+  ): Promise<WeatherResult> {
+    if (!lat || !lng) {
+      throw new HttpException({ error: 'Latitude and longitude are required' }, 400);
+    }
+    try {
+      return await this.weather.get(lat, lng, date, lang ?? 'de');
+    } catch (err: unknown) {
+      throw toHttp(err, 'Weather error:', 'Error fetching weather data');
+    }
+  }
+
+  @Get('detailed')
+  async getDetailed(
+    @Query('lat') lat?: string,
+    @Query('lng') lng?: string,
+    @Query('date') date?: string,
+    @Query('lang') lang?: string,
+  ): Promise<WeatherResult> {
+    if (!lat || !lng || !date) {
+      throw new HttpException({ error: 'Latitude, longitude, and date are required' }, 400);
+    }
+    try {
+      return await this.weather.getDetailed(lat, lng, date, lang ?? 'de');
+    } catch (err: unknown) {
+      throw toHttp(err, 'Detailed weather error:', 'Error fetching detailed weather data');
+    }
+  }
+}
+
+/** Maps a thrown error to the same status + `{ error }` body the Express route sent. */
+function toHttp(err: unknown, logPrefix: string, fallback: string): HttpException {
+  if (err instanceof ApiError) {
+    return new HttpException({ error: err.message }, err.status);
+  }
+  console.error(logPrefix, err);
+  return new HttpException({ error: fallback }, 500);
+}
@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { WeatherController } from './weather.controller';
+import { WeatherService } from './weather.service';
+
+/** Weather domain (pilot leaf module). Registered in AppModule. */
+@Module({
+  controllers: [WeatherController],
+  providers: [WeatherService],
+})
+export class WeatherModule {}
@@ -0,0 +1,21 @@
+import { Injectable } from '@nestjs/common';
+import type { WeatherResult } from '@trek/shared';
+import { getWeather, getDetailedWeather } from '../../services/weatherService';
+
+/**
+ * Thin Nest wrapper around the existing weather service. It delegates to the
+ * exact same `getWeather` / `getDetailedWeather` functions the legacy route and
+ * the MCP tools use, so behaviour — including the shared in-memory cache and the
+ * Open-Meteo calls — is identical. No logic is duplicated; the upstream service
+ * stays the single source of truth (still consumed by the MCP weather tools).
+ */
+@Injectable()
+export class WeatherService {
+  get(lat: string, lng: string, date: string | undefined, lang: string): Promise<WeatherResult> {
+    return getWeather(lat, lng, date, lang) as Promise<WeatherResult>;
+  }
+
+  getDetailed(lat: string, lng: string, date: string, lang: string): Promise<WeatherResult> {
+    return getDetailedWeather(lat, lng, date, lang) as Promise<WeatherResult>;
+  }
+}
@@ -1,45 +0,0 @@
-import express, { Request, Response } from 'express';
-import { authenticate } from '../middleware/auth';
-import { getWeather, getDetailedWeather, ApiError } from '../services/weatherService';
-
-const router = express.Router();
-
-router.get('/', authenticate, async (req: Request, res: Response) => {
-  const { lat, lng, date, lang = 'de' } = req.query as { lat: string; lng: string; date?: string; lang?: string };
-
-  if (!lat || !lng) {
-    return res.status(400).json({ error: 'Latitude and longitude are required' });
-  }
-
-  try {
-    const result = await getWeather(lat, lng, date, lang);
-    res.json(result);
-  } catch (err: unknown) {
-    if (err instanceof ApiError) {
-      return res.status(err.status).json({ error: err.message });
-    }
-    console.error('Weather error:', err);
-    res.status(500).json({ error: 'Error fetching weather data' });
-  }
-});
-
-router.get('/detailed', authenticate, async (req: Request, res: Response) => {
-  const { lat, lng, date, lang = 'de' } = req.query as { lat: string; lng: string; date: string; lang?: string };
-
-  if (!lat || !lng || !date) {
-    return res.status(400).json({ error: 'Latitude, longitude, and date are required' });
-  }
-
-  try {
-    const result = await getDetailedWeather(lat, lng, date, lang);
-    res.json(result);
-  } catch (err: unknown) {
-    if (err instanceof ApiError) {
-      return res.status(err.status).json({ error: err.message });
-    }
-    console.error('Detailed weather error:', err);
-    res.status(500).json({ error: 'Error fetching detailed weather data' });
-  }
-});
-
-export default router;
@@ -0,0 +1,65 @@
+import Database from 'better-sqlite3';
+import jwt from 'jsonwebtoken';
+import { JWT_SECRET } from '../../src/config';
+
+/**
+ * Shared e2e harness for migrated Nest modules.
+ *
+ * Gives each module e2e test a throwaway in-memory SQLite db (the same shape the
+ * shared connection exposes), a seed helper for demo data, and a session-cookie
+ * signer that produces tokens the REAL JwtAuthGuard accepts — so e2e tests cover
+ * the actual auth path end-to-end, not a stubbed guard.
+ *
+ * Wire it in a test with `vi.mock('../../src/db/database', () => ({ db, ... }))`
+ * using the db returned here, then build the Nest app under test.
+ */
+
+export interface SeededUser {
+  id: number;
+  username: string;
+  email: string;
+  role: 'user' | 'admin';
+  password_version: number;
+}
+
+/** Fresh in-memory db with the minimal `users` table the auth guard reads. */
+export function createTempDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA foreign_keys = ON');
+  db.exec(`
+    CREATE TABLE users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      username TEXT NOT NULL,
+      email TEXT NOT NULL UNIQUE,
+      role TEXT NOT NULL DEFAULT 'user',
+      password_version INTEGER NOT NULL DEFAULT 0
+    );
+  `);
+  return db;
+}
+
+/** Insert a demo user and return its row. */
+export function seedUser(db: Database.Database, overrides: Partial<SeededUser> = {}): SeededUser {
+  const user: SeededUser = {
+    id: overrides.id ?? 1,
+    username: overrides.username ?? 'e2e-user',
+    email: overrides.email ?? 'e2e@example.test',
+    role: overrides.role ?? 'user',
+    password_version: overrides.password_version ?? 0,
+  };
+  db.prepare(
+    'INSERT INTO users (id, username, email, role, password_version) VALUES (?, ?, ?, ?, ?)',
+  ).run(user.id, user.username, user.email, user.role, user.password_version);
+  return user;
+}
+
+/** Sign a `trek_session` token the real guard will accept (matching JWT_SECRET + pv). */
+export function signSession(userId: number, passwordVersion = 0): string {
+  return jwt.sign({ id: userId, pv: passwordVersion }, JWT_SECRET, { algorithm: 'HS256' });
+}
+
+/** Convenience: the Cookie header value for a signed session. */
+export function sessionCookie(userId: number, passwordVersion = 0): string {
+  return `trek_session=${signSession(userId, passwordVersion)}`;
+}
@@ -0,0 +1,88 @@
+/**
+ * Weather module e2e — exercises the migrated /api/weather endpoints through the
+ * real JwtAuthGuard against a temp SQLite db (seeded via the shared harness).
+ * The weather service is mocked so no real Open-Meteo calls happen.
+ */
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import request from 'supertest';
+import cookieParser from 'cookie-parser';
+import type { Server } from 'http';
+import { Test } from '@nestjs/testing';
+import { createTempDb, seedUser, sessionCookie } from './harness';
+
+const { db } = vi.hoisted(() => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const Database = require('better-sqlite3');
+  const tmp = new Database(':memory:');
+  tmp.exec('PRAGMA journal_mode = WAL');
+  tmp.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT NOT NULL,
+    email TEXT NOT NULL UNIQUE, role TEXT NOT NULL DEFAULT 'user', password_version INTEGER NOT NULL DEFAULT 0);`);
+  return { db: tmp };
+});
+
+vi.mock('../../src/db/database', () => ({ db, closeDb: () => {}, reinitialize: () => {} }));
+
+const { mockGet, mockGetDetailed } = vi.hoisted(() => ({ mockGet: vi.fn(), mockGetDetailed: vi.fn() }));
+vi.mock('../../src/services/weatherService', async (importActual) => {
+  const actual = await importActual<typeof import('../../src/services/weatherService')>();
+  return { ...actual, getWeather: mockGet, getDetailedWeather: mockGetDetailed };
+});
+
+import { WeatherModule } from '../../src/nest/weather/weather.module';
+import { TrekExceptionFilter } from '../../src/nest/common/trek-exception.filter';
+
+describe('Weather e2e (real auth guard + temp SQLite)', () => {
+  let server: Server;
+  let app: Awaited<ReturnType<typeof build>>;
+
+  async function build() {
+    const moduleRef = await Test.createTestingModule({ imports: [WeatherModule] }).compile();
+    const nest = moduleRef.createNestApplication();
+    nest.use(cookieParser());
+    nest.useGlobalFilters(new TrekExceptionFilter());
+    await nest.init();
+    return nest;
+  }
+
+  beforeAll(async () => {
+    seedUser(db as never, { id: 1 });
+    app = await build();
+    server = app.getHttpServer();
+    mockGet.mockResolvedValue({ temp: 21, main: 'Clear', description: 'Klar', type: 'current' });
+    mockGetDetailed.mockResolvedValue({ temp: 20, main: 'Rain', description: 'Regen', type: 'forecast', hourly: [] });
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('401 { error, code } without a session cookie', async () => {
+    const res = await request(server).get('/api/weather').query({ lat: '1', lng: '2' });
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: 'Access token required', code: 'AUTH_REQUIRED' });
+  });
+
+  it('401 with an invalid token', async () => {
+    const res = await request(server).get('/api/weather').set('Cookie', 'trek_session=not-a-jwt').query({ lat: '1', lng: '2' });
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: 'Invalid or expired token', code: 'AUTH_REQUIRED' });
+  });
+
+  it('400 when authenticated but lat/lng missing', async () => {
+    const res = await request(server).get('/api/weather').set('Cookie', sessionCookie(1)).query({ lng: '2' });
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: 'Latitude and longitude are required' });
+  });
+
+  it('200 with a valid session cookie', async () => {
+    const res = await request(server).get('/api/weather').set('Cookie', sessionCookie(1)).query({ lat: '52.5', lng: '13.4' });
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({ temp: 21, main: 'Clear', type: 'current' });
+  });
+
+  it('200 on /detailed with a valid session cookie', async () => {
+    const res = await request(server).get('/api/weather/detailed').set('Cookie', sessionCookie(1)).query({ lat: '1', lng: '2', date: '2026-07-01' });
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({ type: 'forecast' });
+  });
+});
@@ -1,262 +0,0 @@
-/**
- * Weather integration tests.
- * Covers WEATHER-001 to WEATHER-007.
- *
- * External API calls (Open-Meteo) are mocked via vi.mock.
- */
-import { describe, it, expect, vi, beforeAll, beforeEach, afterAll } from 'vitest';
-import request from 'supertest';
-import type { Application } from 'express';
-
-const { testDb, dbMock } = vi.hoisted(() => {
-  const Database = require('better-sqlite3');
-  const db = new Database(':memory:');
-  db.exec('PRAGMA journal_mode = WAL');
-  db.exec('PRAGMA foreign_keys = ON');
-  db.exec('PRAGMA busy_timeout = 5000');
-  const mock = {
-    db,
-    closeDb: () => {},
-    reinitialize: () => {},
-    getPlaceWithTags: (placeId: number) => {
-      const place: any = db.prepare(`SELECT p.*, c.name as category_name, c.color as category_color, c.icon as category_icon FROM places p LEFT JOIN categories c ON p.category_id = c.id WHERE p.id = ?`).get(placeId);
-      if (!place) return null;
-      const tags = db.prepare(`SELECT t.* FROM tags t JOIN place_tags pt ON t.id = pt.tag_id WHERE pt.place_id = ?`).all(placeId);
-      return { ...place, category: place.category_id ? { id: place.category_id, name: place.category_name, color: place.category_color, icon: place.category_icon } : null, tags };
-    },
-    canAccessTrip: (tripId: any, userId: number) =>
-      db.prepare(`SELECT t.id, t.user_id FROM trips t LEFT JOIN trip_members m ON m.trip_id = t.id AND m.user_id = ? WHERE t.id = ? AND (t.user_id = ? OR m.user_id IS NOT NULL)`).get(userId, tripId, userId),
-    isOwner: (tripId: any, userId: number) =>
-      !!db.prepare('SELECT id FROM trips WHERE id = ? AND user_id = ?').get(tripId, userId),
-  };
-  return { testDb: db, dbMock: mock };
-});
-
-vi.mock('../../src/db/database', () => dbMock);
-vi.mock('../../src/config', () => ({
-  JWT_SECRET: 'test-jwt-secret-for-trek-testing-only',
-  ENCRYPTION_KEY: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2',
-  updateJwtSecret: () => {},
-}));
-
-// Prevent real HTTP calls to Open-Meteo
-vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-  ok: true,
-  json: () => Promise.resolve({
-    current: { temperature_2m: 22, weathercode: 1, windspeed_10m: 10, relativehumidity_2m: 60, precipitation: 0 },
-    daily: {
-      time: ['2025-06-01'],
-      temperature_2m_max: [25],
-      temperature_2m_min: [18],
-      weathercode: [1],
-      precipitation_sum: [0],
-      windspeed_10m_max: [15],
-      sunrise: ['2025-06-01T06:00'],
-      sunset: ['2025-06-01T21:00'],
-    },
-  }),
-}));
-
-import { createApp } from '../../src/app';
-import { createTables } from '../../src/db/schema';
-import { runMigrations } from '../../src/db/migrations';
-import { resetTestDb } from '../helpers/test-db';
-import { createUser } from '../helpers/factories';
-import { authCookie } from '../helpers/auth';
-import { loginAttempts, mfaAttempts } from '../../src/routes/auth';
-
-const app: Application = createApp();
-
-beforeAll(() => {
-  createTables(testDb);
-  runMigrations(testDb);
-});
-
-beforeEach(() => {
-  resetTestDb(testDb);
-  loginAttempts.clear();
-  mfaAttempts.clear();
-});
-
-afterAll(() => {
-  testDb.close();
-  vi.unstubAllGlobals();
-});
-
-describe('Weather validation', () => {
-  it('WEATHER-001 — GET /weather without lat/lng returns 400', async () => {
-    const { user } = createUser(testDb);
-
-    const res = await request(app)
-      .get('/api/weather')
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(400);
-  });
-
-  it('WEATHER-001 — GET /weather without lng returns 400', async () => {
-    const { user } = createUser(testDb);
-
-    const res = await request(app)
-      .get('/api/weather?lat=48.8566')
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(400);
-  });
-
-  it('WEATHER-005 — GET /weather/detailed without date returns 400', async () => {
-    const { user } = createUser(testDb);
-
-    const res = await request(app)
-      .get('/api/weather/detailed?lat=48.8566&lng=2.3522')
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(400);
-  });
-
-  it('WEATHER-001 — GET /weather without auth returns 401', async () => {
-    const res = await request(app)
-      .get('/api/weather?lat=48.8566&lng=2.3522');
-    expect(res.status).toBe(401);
-  });
-});
-
-describe('Weather with mocked API', () => {
-  it('WEATHER-001 — GET /weather with lat/lng returns weather data', async () => {
-    const { user } = createUser(testDb);
-
-    const res = await request(app)
-      .get('/api/weather?lat=48.8566&lng=2.3522')
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(200);
-    expect(res.body).toHaveProperty('temp');
-    expect(res.body).toHaveProperty('main');
-  });
-
-  it('WEATHER-002 — GET /weather?date=future returns forecast data', async () => {
-    const { user } = createUser(testDb);
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + 5);
-    const dateStr = futureDate.toISOString().slice(0, 10);
-
-    const res = await request(app)
-      .get(`/api/weather?lat=48.8566&lng=2.3522&date=${dateStr}`)
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(200);
-    expect(res.body).toHaveProperty('temp');
-    expect(res.body).toHaveProperty('type');
-  });
-
-  it('WEATHER-006 — GET /weather accepts lang parameter', async () => {
-    const { user } = createUser(testDb);
-
-    const res = await request(app)
-      .get('/api/weather?lat=48.8566&lng=2.3522&lang=en')
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(200);
-    expect(res.body).toHaveProperty('temp');
-  });
-
-  it('WEATHER-007 — GET /weather returns 500 on non-ok API response (ApiError path)', async () => {
-    const { user } = createUser(testDb);
-    // Use unique coords to avoid cache from previous tests
-    vi.mocked(global.fetch as any).mockResolvedValueOnce({
-      ok: false,
-      status: 503,
-      json: () => Promise.resolve({ error: true, reason: 'Service unavailable' }),
-    });
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + 3);
-    const dateStr = futureDate.toISOString().slice(0, 10);
-
-    const res = await request(app)
-      .get(`/api/weather?lat=55.0&lng=25.0&date=${dateStr}`)
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(503);
-    expect(res.body).toHaveProperty('error');
-  });
-
-  it('WEATHER-008 — GET /weather returns 500 on network error (generic error path)', async () => {
-    const { user } = createUser(testDb);
-    vi.mocked(global.fetch as any).mockRejectedValueOnce(new Error('Network error'));
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + 4);
-    const dateStr = futureDate.toISOString().slice(0, 10);
-
-    const res = await request(app)
-      .get(`/api/weather?lat=56.0&lng=26.0&date=${dateStr}`)
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(500);
-    expect(res.body).toHaveProperty('error');
-  });
-
-  it('WEATHER-009 — GET /weather/detailed returns detailed weather data', async () => {
-    const { user } = createUser(testDb);
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + 2);
-    const dateStr = futureDate.toISOString().slice(0, 10);
-
-    // Override mock with full detailed forecast response
-    vi.mocked(global.fetch as any).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({
-        daily: {
-          time: [dateStr],
-          temperature_2m_max: [24],
-          temperature_2m_min: [16],
-          weathercode: [1],
-          precipitation_sum: [0],
-          windspeed_10m_max: [12],
-          sunrise: [`${dateStr}T06:00`],
-          sunset: [`${dateStr}T21:00`],
-          precipitation_probability_max: [10],
-        },
-        hourly: {
-          time: [`${dateStr}T12:00`],
-          temperature_2m: [20],
-          precipitation_probability: [5],
-          precipitation: [0],
-          weathercode: [1],
-          windspeed_10m: [10],
-          relativehumidity_2m: [55],
-        },
-      }),
-    });
-
-    const res = await request(app)
-      .get(`/api/weather/detailed?lat=50.0&lng=10.0&date=${dateStr}`)
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(200);
-    expect(res.body).toHaveProperty('temp');
-    expect(res.body.type).toBe('forecast');
-  });
-
-  it('WEATHER-010 — GET /weather/detailed returns error status on ApiError', async () => {
-    const { user } = createUser(testDb);
-    vi.mocked(global.fetch as any).mockResolvedValueOnce({
-      ok: false,
-      status: 502,
-      json: () => Promise.resolve({ error: true, reason: 'Bad Gateway' }),
-    });
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + 6);
-    const dateStr = futureDate.toISOString().slice(0, 10);
-
-    const res = await request(app)
-      .get(`/api/weather/detailed?lat=57.0&lng=27.0&date=${dateStr}`)
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(502);
-    expect(res.body).toHaveProperty('error');
-  });
-
-  it('WEATHER-011 — GET /weather/detailed returns 500 on network error', async () => {
-    const { user } = createUser(testDb);
-    vi.mocked(global.fetch as any).mockRejectedValueOnce(new Error('Network error'));
-    const futureDate = new Date();
-    futureDate.setDate(futureDate.getDate() + 7);
-    const dateStr = futureDate.toISOString().slice(0, 10);
-
-    const res = await request(app)
-      .get(`/api/weather/detailed?lat=58.0&lng=28.0&date=${dateStr}`)
-      .set('Cookie', authCookie(user.id));
-    expect(res.status).toBe(500);
-    expect(res.body).toHaveProperty('error');
-  });
-});
@@ -0,0 +1,39 @@
+import request from 'supertest';
+import { expect } from 'vitest';
+import type { Server } from 'http';
+
+export interface ParityRequest {
+  method?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+  path: string;
+  query?: Record<string, string>;
+  body?: unknown;
+}
+
+/**
+ * Reusable Nest-vs-Express parity harness.
+ *
+ * Fires the same HTTP request at the legacy Express app and the migrated Nest app
+ * and asserts the response is client-identical — same status code and same JSON
+ * body. With the underlying service mocked identically for both, any difference is
+ * purely framework-layer (routing, validation, error envelope), which is exactly
+ * what a migration must not change. Use one assertion per migrated route/case.
+ */
+export async function expectParity(
+  expressServer: Server | Express.Application,
+  nestServer: Server,
+  req: ParityRequest,
+): Promise<void> {
+  const fire = (target: Server | Express.Application) => {
+    const method = req.method ?? 'get';
+    let r = request(target as never)[method](req.path);
+    if (req.query) r = r.query(req.query);
+    if (req.body !== undefined) r = r.send(req.body as object);
+    return r;
+  };
+
+  const [ex, ne] = await Promise.all([fire(expressServer), fire(nestServer)]);
+
+  const label = `${(req.method ?? 'GET').toUpperCase()} ${req.path}`;
+  expect(ne.status, `${label}: status mismatch`).toBe(ex.status);
+  expect(ne.body, `${label}: body mismatch`).toEqual(ex.body);
+}
@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { HttpException } from '@nestjs/common';
+import { JwtAuthGuard } from '../../../src/nest/auth/jwt-auth.guard';
+
+function context(req: unknown) {
+  return { switchToHttp: () => ({ getRequest: () => req }) } as never;
+}
+
+describe('JwtAuthGuard', () => {
+  const guard = new JwtAuthGuard();
+
+  it('rejects with the legacy 401 { error, code } when no token is present', () => {
+    let thrown: unknown;
+    try {
+      guard.canActivate(context({ headers: {}, cookies: {} }));
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(HttpException);
+    expect((thrown as HttpException).getStatus()).toBe(401);
+    expect((thrown as HttpException).getResponse()).toEqual({
+      error: 'Access token required',
+      code: 'AUTH_REQUIRED',
+    });
+  });
+});
@@ -0,0 +1,36 @@
+/**
+ * DatabaseService — the shared better-sqlite3 provider (F3). Exercises every
+ * helper against the real connection so the typed query surface is covered.
+ */
+import { describe, it, expect } from 'vitest';
+import { DatabaseService } from '../../../src/nest/database/database.service';
+
+describe('DatabaseService (typed query helpers)', () => {
+  const svc = new DatabaseService();
+
+  it('exposes the shared connection', () => {
+    expect(typeof svc.connection.prepare).toBe('function');
+  });
+
+  it('prepare + get + all return rows from the live connection', () => {
+    expect(svc.prepare('SELECT 1 AS one').get()).toEqual({ one: 1 });
+    expect(svc.get('SELECT 2 AS two')).toEqual({ two: 2 });
+    expect(svc.all('SELECT 3 AS three')).toEqual([{ three: 3 }]);
+  });
+
+  it('run + transaction operate on a scratch table', () => {
+    svc.run('CREATE TEMP TABLE IF NOT EXISTS _dbsvc_test (n INTEGER)');
+    svc.run('DELETE FROM _dbsvc_test');
+
+    const info = svc.run('INSERT INTO _dbsvc_test (n) VALUES (?)', 41);
+    expect(info.changes).toBe(1);
+
+    const total = svc.transaction((conn) => {
+      conn.prepare('INSERT INTO _dbsvc_test (n) VALUES (?)').run(1);
+      return conn.prepare('SELECT SUM(n) AS s FROM _dbsvc_test').get() as { s: number };
+    });
+    expect(total.s).toBe(42);
+
+    svc.run('DROP TABLE _dbsvc_test');
+  });
+});
@@ -0,0 +1,34 @@
+import { describe, it, expect, vi } from 'vitest';
+import { HttpException } from '@nestjs/common';
+import { TrekExceptionFilter } from '../../../src/nest/common/trek-exception.filter';
+
+function mockHost() {
+  const res = { status: vi.fn().mockReturnThis(), json: vi.fn().mockReturnThis() };
+  const host = { switchToHttp: () => ({ getResponse: () => res }) } as never;
+  return { res, host };
+}
+
+describe('TrekExceptionFilter', () => {
+  const filter = new TrekExceptionFilter();
+
+  it('passes through { error, code } bodies (auth guards) unchanged', () => {
+    const { res, host } = mockHost();
+    filter.catch(new HttpException({ error: 'Access token required', code: 'AUTH_REQUIRED' }, 401), host);
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({ error: 'Access token required', code: 'AUTH_REQUIRED' });
+  });
+
+  it('normalises a string HttpException to { error }', () => {
+    const { res, host } = mockHost();
+    filter.catch(new HttpException('Bad thing', 400), host);
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(res.json).toHaveBeenCalledWith({ error: 'Bad thing' });
+  });
+
+  it('maps unknown errors to 500 { error: Internal server error }', () => {
+    const { res, host } = mockHost();
+    filter.catch(new Error('boom'), host);
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(res.json).toHaveBeenCalledWith({ error: 'Internal server error' });
+  });
+});
@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { HealthController } from '../../../src/nest/health/health.controller';
+import { HealthService } from '../../../src/nest/health/health.service';
+import { DatabaseService } from '../../../src/nest/database/database.service';
+
+describe('Nest dependency injection (vitest + swc)', () => {
+  it('injects HealthService + DatabaseService into HealthController by type', async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [HealthController],
+      providers: [
+        HealthService,
+        { provide: DatabaseService, useValue: { get: () => ({ n: 7 }) } },
+      ],
+    }).compile();
+
+    const controller = moduleRef.get(HealthController);
+    expect(controller.getHealth()).toEqual({
+      ok: true,
+      runtime: 'nestjs',
+      diInjected: true,
+      userCount: 7,
+    });
+  });
+});
@@ -0,0 +1,33 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { getNestPrefixes, makeNestPathMatcher } from '../../../src/nest/strangler';
+
+describe('strangler toggle', () => {
+  const original = process.env.NEST_PREFIXES;
+  afterEach(() => {
+    if (original === undefined) delete process.env.NEST_PREFIXES;
+    else process.env.NEST_PREFIXES = original;
+  });
+
+  it('defaults to the migrated prefixes (/api/_nest + /api/weather) when NEST_PREFIXES is unset', () => {
+    delete process.env.NEST_PREFIXES;
+    expect(getNestPrefixes()).toEqual(['/api/_nest', '/api/weather']);
+  });
+
+  it('parses NEST_PREFIXES (comma-separated, trimmed)', () => {
+    process.env.NEST_PREFIXES = '/api/weather, /api/airports';
+    expect(getNestPrefixes()).toEqual(['/api/weather', '/api/airports']);
+  });
+
+  it('treats an empty NEST_PREFIXES as "all routes on legacy"', () => {
+    process.env.NEST_PREFIXES = '';
+    expect(getNestPrefixes()).toEqual([]);
+  });
+
+  it('matches exact prefixes and subpaths but not lookalikes', () => {
+    const match = makeNestPathMatcher(['/api/_nest']);
+    expect(match('/api/_nest')).toBe(true);
+    expect(match('/api/_nest/health')).toBe(true);
+    expect(match('/api/_nestxyz')).toBe(false);
+    expect(match('/api/health')).toBe(false);
+  });
+});
@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from 'vitest';
+import { HttpException } from '@nestjs/common';
+import { WeatherController } from '../../../src/nest/weather/weather.controller';
+import { ApiError } from '../../../src/services/weatherService';
+import type { WeatherService } from '../../../src/nest/weather/weather.service';
+
+function makeController(svc: Partial<WeatherService>) {
+  return new WeatherController(svc as WeatherService);
+}
+
+/** Run `fn`, expecting it to throw an HttpException; return its { status, body }. */
+async function thrown(fn: () => Promise<unknown>): Promise<{ status: number; body: unknown }> {
+  try {
+    await fn();
+  } catch (err) {
+    expect(err).toBeInstanceOf(HttpException);
+    const e = err as HttpException;
+    return { status: e.getStatus(), body: e.getResponse() };
+  }
+  throw new Error('expected the handler to throw');
+}
+
+describe('WeatherController (parity with the legacy /api/weather route)', () => {
+  const sample = { temp: 21, main: 'Clear', description: 'Klar', type: 'current' };
+
+  describe('GET /api/weather', () => {
+    it('400 { error } with the exact legacy message when lat/lng missing', async () => {
+      const c = makeController({ get: vi.fn() });
+      expect(await thrown(() => c.getWeather(undefined, '13.4'))).toEqual({
+        status: 400,
+        body: { error: 'Latitude and longitude are required' },
+      });
+    });
+
+    it('returns the service result and defaults lang to "de" when absent', async () => {
+      const get = vi.fn().mockResolvedValue(sample);
+      const c = makeController({ get });
+      const res = await c.getWeather('52.5', '13.4', undefined, undefined);
+      expect(res).toEqual(sample);
+      expect(get).toHaveBeenCalledWith('52.5', '13.4', undefined, 'de');
+    });
+
+    it('passes an explicit lang and date through unchanged', async () => {
+      const get = vi.fn().mockResolvedValue(sample);
+      const c = makeController({ get });
+      await c.getWeather('1', '2', '2026-07-01', 'en');
+      expect(get).toHaveBeenCalledWith('1', '2', '2026-07-01', 'en');
+    });
+
+    it('maps an ApiError to its status + { error: message }', async () => {
+      const c = makeController({ get: vi.fn().mockRejectedValue(new ApiError(404, 'Open-Meteo API error')) });
+      expect(await thrown(() => c.getWeather('1', '2'))).toEqual({
+        status: 404,
+        body: { error: 'Open-Meteo API error' },
+      });
+    });
+
+    it('maps an unexpected error to the exact legacy 500 body', async () => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+      const c = makeController({ get: vi.fn().mockRejectedValue(new Error('boom')) });
+      expect(await thrown(() => c.getWeather('1', '2'))).toEqual({
+        status: 500,
+        body: { error: 'Error fetching weather data' },
+      });
+    });
+  });
+
+  describe('GET /api/weather/detailed', () => {
+    it('400 { error } with the exact legacy message when date missing', async () => {
+      const c = makeController({ getDetailed: vi.fn() });
+      expect(await thrown(() => c.getDetailed('1', '2', undefined))).toEqual({
+        status: 400,
+        body: { error: 'Latitude, longitude, and date are required' },
+      });
+    });
+
+    it('returns the detailed result and defaults lang to "de"', async () => {
+      const getDetailed = vi.fn().mockResolvedValue(sample);
+      const c = makeController({ getDetailed });
+      await c.getDetailed('1', '2', '2026-07-01', undefined);
+      expect(getDetailed).toHaveBeenCalledWith('1', '2', '2026-07-01', 'de');
+    });
+
+    it('maps an unexpected error to the exact detailed 500 body', async () => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+      const c = makeController({ getDetailed: vi.fn().mockRejectedValue(new Error('boom')) });
+      expect(await thrown(() => c.getDetailed('1', '2', '2026-07-01'))).toEqual({
+        status: 500,
+        body: { error: 'Error fetching detailed weather data' },
+      });
+    });
+  });
+});
@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { HttpException } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import { AppModule } from '../../../src/nest/app.module';
+import { HealthController } from '../../../src/nest/health/health.controller';
+import { DatabaseService } from '../../../src/nest/database/database.service';
+import { AdminGuard } from '../../../src/nest/auth/admin.guard';
+
+function ctx(user: unknown) {
+  return { switchToHttp: () => ({ getRequest: () => ({ user }) }) } as never;
+}
+
+describe('AppModule wiring', () => {
+  it('compiles with the global filter + DB provider and resolves the controller', async () => {
+    const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
+      .overrideProvider(DatabaseService)
+      .useValue({ get: () => ({ n: 0 }) })
+      .compile();
+    expect(moduleRef.get(HealthController)).toBeInstanceOf(HealthController);
+  });
+});
+
+describe('AdminGuard', () => {
+  const guard = new AdminGuard();
+  it('allows admins', () => {
+    expect(guard.canActivate(ctx({ role: 'admin' }))).toBe(true);
+  });
+  it('blocks non-admins and anonymous with 403 { error }', () => {
+    expect(() => guard.canActivate(ctx({ role: 'user' }))).toThrow(HttpException);
+    expect(() => guard.canActivate(ctx(undefined))).toThrow(HttpException);
+  });
+});
+
+describe('DatabaseService (shared connection)', () => {
+  it('runs real queries against the existing SQLite connection', () => {
+    const svc = new DatabaseService();
+    expect(svc.get('SELECT 1 AS one')).toEqual({ one: 1 });
+    expect(svc.all('SELECT 1 AS one')).toEqual([{ one: 1 }]);
+  });
+});
@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { HttpException } from '@nestjs/common';
+import { ZodValidationPipe } from '../../../src/nest/common/zod-validation.pipe';
+
+describe('ZodValidationPipe', () => {
+  const pipe = new ZodValidationPipe(z.object({ name: z.string().min(1) }));
+  const meta = {} as never;
+
+  it('returns the parsed value for valid input', () => {
+    expect(pipe.transform({ name: 'x' }, meta)).toEqual({ name: 'x' });
+  });
+
+  it('throws TREK { error } envelope with status 400 on invalid input', () => {
+    let thrown: unknown;
+    try {
+      pipe.transform({ name: '' }, meta);
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(HttpException);
+    expect((thrown as HttpException).getStatus()).toBe(400);
+    expect((thrown as HttpException).getResponse()).toHaveProperty('error');
+  });
+});
@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+// Smoke test: proves the server toolchain (tsx / vitest) resolves @trek/shared.
+import { idParamSchema, paginationQuerySchema } from '@trek/shared';
+
+describe('@trek/shared resolves in the server toolchain', () => {
+  it('imports and uses a shared schema', () => {
+    expect(idParamSchema.parse('7')).toBe(7);
+    expect(paginationQuerySchema.parse({})).toEqual({ page: 1, perPage: 50 });
+  });
+});
@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "noEmitOnError": false,
+    "outDir": "./dist",
+    "sourceMap": false,
+    "declaration": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests", "**/*.spec.ts", "**/*.test.ts"]
+}
@@ -3,6 +3,9 @@
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "baseUrl": ".",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": false,
@@ -19,16 +22,18 @@
    // (e.g. "./*": "./dist/esm/*") which TypeScript cannot resolve — it only strips .js suffixes.
    // These paths manually redirect to the CJS dist until the SDK fixes its exports map.
    "paths": {
-      "@modelcontextprotocol/sdk/server/mcp": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp"],
-      "@modelcontextprotocol/sdk/server/streamableHttp": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/streamableHttp"],
-      "@modelcontextprotocol/sdk/server/auth/router": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/router"],
-      "@modelcontextprotocol/sdk/server/auth/handlers/authorize": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/handlers/authorize"],
-      "@modelcontextprotocol/sdk/server/auth/handlers/register": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/handlers/register"],
-      "@modelcontextprotocol/sdk/server/auth/provider": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/provider"],
-      "@modelcontextprotocol/sdk/server/auth/clients": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/clients"],
-      "@modelcontextprotocol/sdk/server/auth/errors": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/errors"],
-      "@modelcontextprotocol/sdk/server/auth/types": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/types"],
-      "@modelcontextprotocol/sdk/shared/auth": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/shared/auth"]
+      "@trek/shared": ["../shared/src/index.ts"],
+      "@trek/shared/*": ["../shared/src/*"],
+      "@modelcontextprotocol/sdk/server/mcp": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js"],
+      "@modelcontextprotocol/sdk/server/streamableHttp": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/streamableHttp.js"],
+      "@modelcontextprotocol/sdk/server/auth/router": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/router.js"],
+      "@modelcontextprotocol/sdk/server/auth/handlers/authorize": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/handlers/authorize.js"],
+      "@modelcontextprotocol/sdk/server/auth/handlers/register": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/handlers/register.js"],
+      "@modelcontextprotocol/sdk/server/auth/provider": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/provider.js"],
+      "@modelcontextprotocol/sdk/server/auth/clients": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/clients.js"],
+      "@modelcontextprotocol/sdk/server/auth/errors": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/errors.js"],
+      "@modelcontextprotocol/sdk/server/auth/types": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/server/auth/types.js"],
+      "@modelcontextprotocol/sdk/shared/auth": ["./node_modules/@modelcontextprotocol/sdk/dist/cjs/shared/auth.js"]
    }
  },
  "include": ["src"],
@@ -1,6 +1,18 @@
 import { defineConfig } from 'vitest/config';
+import swc from 'unplugin-swc';

 export default defineConfig({
+  // SWC transform so NestJS decorator metadata is emitted in tests
+  // (vitest's default esbuild does not emit it -> type-based DI would break).
+  plugins: [
+    swc.vite({
+      jsc: {
+        parser: { syntax: 'typescript', decorators: true },
+        transform: { legacyDecorator: true, decoratorMetadata: true },
+        keepClassNames: true,
+      },
+    }),
+  ],
  test: {
    root: '.',
    include: ['tests/**/*.test.ts'],
@@ -16,10 +28,19 @@ export default defineConfig({
      reporter: ['lcov', 'text'],
      reportsDirectory: './coverage',
      include: ['src/**/*.ts'],
+      // Coverage gate scoped to the new NestJS code only — the legacy codebase
+      // is intentionally ungated. Raised to the DoD's >=80% bar once the first
+      // module (weather) landed; ratchet further as more modules are migrated.
+      thresholds: {
+        'src/nest/**/*.ts': { statements: 80, branches: 80, functions: 80, lines: 80 },
+      },
    },
  },
  resolve: {
    alias: {
+      // @trek/shared — Zod contract package (tests resolve it to TS source,
+      // mirroring the tsconfig `paths` the tsx runtime uses).
+      '@trek/shared': new URL('../shared/src/index.ts', import.meta.url).pathname,
      '@modelcontextprotocol/sdk/server/mcp': new URL(
          './node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js',
          import.meta.url
@@ -37,5 +58,12 @@ export default defineConfig({
          import.meta.url
      ).pathname,
    },
+    // The server build emits @trek/shared next to its source (shared/src/*.js,
+    // needed by the prod dist via tsc-alias). Vite's default extension order
+    // prefers .js over .ts, so after a build the tests would load that compiled
+    // CJS instead of the source — and its `require('zod')` is unresolvable from
+    // the shared/ dir on CI (only server deps are installed there). Resolve .ts
+    // first so tests always run the source, whose zod import resolves via Vite.
+    extensions: ['.ts', '.mts', '.mjs', '.js', '.cts', '.cjs', '.tsx', '.jsx', '.json'],
  },
 });
@@ -0,0 +1,32 @@
+# @trek/shared
+
+Single source of truth for TREK's API contracts, expressed as [Zod](https://zod.dev) schemas
+and consumed by **both** the server (request validation + inferred DTO types) and the client
+(typed requests/responses).
+
+This package is part of the incremental NestJS + React 19 migration
+(see the "Brownfield Rewrite" board). It is intentionally **dormant** until modules start
+importing it — adding it changes nothing for users.
+
+## Rules
+
+- **One folder per domain**: `src/<domain>/<domain>.schema.ts` (+ `.spec.ts`).
+- Domain-agnostic building blocks live in `src/common/`.
+- A route is only considered **migrated** once its contract lives here.
+- Schemas are the source of truth; server DTOs and client types are *inferred* from them
+  (`z.infer<typeof schema>`), never hand-duplicated.
+
+## Consumption (dev)
+
+Both apps resolve `@trek/shared` to this package's TypeScript source:
+
+- **Server** (`tsx`): via `paths` in `server/tsconfig.json`.
+- **Client** (`vite`): via `resolve.alias` in `client/vite.config.ts` (+ `paths` for the type-checker).
+
+> Production packaging (Docker / workspace wiring) is introduced in card **F2**, when the
+> server first depends on this package at runtime. Until then prod builds are untouched.
+
+## Not yet here
+
+The canonical **error envelope** is finalised in card **F5** (it must match TREK's current
+Express error responses byte-for-byte), so it is deliberately not invented in F1.
@@ -0,0 +1,25 @@
+{
+  "name": "@trek/shared",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Shared API contracts (Zod schemas) — single source of truth for TREK server and client.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "^3.2.4"
+  }
+}
@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+/**
+ * Generic pagination query helper. Individual endpoints opt in by extending
+ * this; it is NOT applied globally (many TREK list endpoints return full sets).
+ * Defaults are conservative and only used where a route already paginates.
+ */
+export const paginationQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  perPage: z.coerce.number().int().min(1).max(200).default(50),
+});
+export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { idSchema, idParamSchema, nonEmptyString, isoDateTime } from './primitives.schema';
+import { paginationQuerySchema } from './pagination.schema';
+
+describe('@trek/shared primitives', () => {
+  it('idSchema accepts positive integers, rejects others', () => {
+    expect(idSchema.parse(1)).toBe(1);
+    expect(idSchema.safeParse(0).success).toBe(false);
+    expect(idSchema.safeParse(-3).success).toBe(false);
+    expect(idSchema.safeParse(1.5).success).toBe(false);
+  });
+
+  it('idParamSchema coerces string params to a positive int', () => {
+    expect(idParamSchema.parse('42')).toBe(42);
+    expect(idParamSchema.safeParse('abc').success).toBe(false);
+  });
+
+  it('nonEmptyString trims and rejects empty', () => {
+    expect(nonEmptyString.parse('  hi ')).toBe('hi');
+    expect(nonEmptyString.safeParse('   ').success).toBe(false);
+  });
+
+  it('isoDateTime accepts an ISO timestamp', () => {
+    expect(isoDateTime.safeParse('2026-05-25T08:38:14Z').success).toBe(true);
+    expect(isoDateTime.safeParse('not-a-date').success).toBe(false);
+  });
+});
+
+describe('@trek/shared pagination', () => {
+  it('applies defaults and coerces', () => {
+    expect(paginationQuerySchema.parse({})).toEqual({ page: 1, perPage: 50 });
+    expect(paginationQuerySchema.parse({ page: '2', perPage: '10' })).toEqual({ page: 2, perPage: 10 });
+  });
+
+  it('enforces bounds', () => {
+    expect(paginationQuerySchema.safeParse({ perPage: 0 }).success).toBe(false);
+    expect(paginationQuerySchema.safeParse({ perPage: 999 }).success).toBe(false);
+  });
+});
@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * Primitive, domain-agnostic building blocks shared by every contract.
+ * Domain schemas (trips, places, ...) live in their own folders and reuse these.
+ */
+
+/** TREK uses auto-increment integer primary keys. */
+export const idSchema = z.number().int().positive();
+export type Id = z.infer<typeof idSchema>;
+
+/**
+ * Numeric id coming from a URL param / query string. Express hands these over
+ * as strings, so we coerce, then enforce a positive integer.
+ */
+export const idParamSchema = z.coerce.number().int().positive();
+
+/** Non-empty, trimmed string. */
+export const nonEmptyString = z.string().trim().min(1);
+
+/** ISO-8601 timestamp string (the shape TREK serialises dates as in JSON). */
+export const isoDateTime = z.string().datetime({ offset: true });
@@ -0,0 +1,15 @@
+/**
+ * @trek/shared — single source of truth for TREK's API contracts.
+ *
+ * Zod schemas defined here are consumed by BOTH the server (validation +
+ * inferred DTO types) and the client (typed requests/responses). A route is
+ * only considered "migrated" once its contract lives in this package.
+ *
+ * Layout: one folder per domain (e.g. src/trip/trip.schema.ts), plus the
+ * domain-agnostic primitives below. See the board card "Module blueprint".
+ */
+export * from './common/primitives.schema';
+export * from './common/pagination.schema';
+
+// Domain contracts
+export * from './weather/weather.schema';
@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import {
+  weatherQuerySchema,
+  detailedWeatherQuerySchema,
+  weatherResultSchema,
+} from './weather.schema';
+
+describe('weatherQuerySchema', () => {
+  it('accepts lat/lng and defaults lang to "de"', () => {
+    const parsed = weatherQuerySchema.parse({ lat: '52.5', lng: '13.4' });
+    expect(parsed).toEqual({ lat: '52.5', lng: '13.4', lang: 'de' });
+  });
+
+  it('keeps an explicit lang and optional date', () => {
+    const parsed = weatherQuerySchema.parse({ lat: '1', lng: '2', date: '2026-07-01', lang: 'en' });
+    expect(parsed.lang).toBe('en');
+    expect(parsed.date).toBe('2026-07-01');
+  });
+
+  it('rejects missing lat/lng', () => {
+    expect(weatherQuerySchema.safeParse({ lng: '13.4' }).success).toBe(false);
+    expect(weatherQuerySchema.safeParse({ lat: '', lng: '13.4' }).success).toBe(false);
+  });
+});
+
+describe('detailedWeatherQuerySchema', () => {
+  it('requires a date', () => {
+    expect(detailedWeatherQuerySchema.safeParse({ lat: '1', lng: '2' }).success).toBe(false);
+    expect(detailedWeatherQuerySchema.safeParse({ lat: '1', lng: '2', date: '2026-07-01' }).success).toBe(true);
+  });
+});
+
+describe('weatherResultSchema', () => {
+  it('accepts a minimal current-weather result', () => {
+    const r = weatherResultSchema.parse({ temp: 21, main: 'Clear', description: 'Klar', type: 'current' });
+    expect(r.temp).toBe(21);
+  });
+
+  it('accepts a detailed result with hourly entries and a no_forecast error', () => {
+    expect(
+      weatherResultSchema.safeParse({
+        temp: 0, main: '', description: '', type: '', error: 'no_forecast',
+      }).success,
+    ).toBe(true);
+    expect(
+      weatherResultSchema.safeParse({
+        temp: 18, main: 'Rain', description: 'Regen', type: 'forecast',
+        sunrise: '05:30', sunset: '21:10', precipitation_sum: 2.4,
+        hourly: [{ hour: 9, temp: 17, precipitation: 0.1, precipitation_probability: 20, main: 'Clouds', wind: 12, humidity: 80 }],
+      }).success,
+    ).toBe(true);
+  });
+});
@@ -0,0 +1,60 @@
+import { z } from 'zod';
+
+/**
+ * Weather API contract — single source of truth for the /api/weather endpoints.
+ *
+ * The legacy Express routes treat lat/lng as opaque strings (they are parsed with
+ * parseFloat inside the service) and only check for presence, so the query schemas
+ * mirror that: non-empty strings, not coerced numbers. `lang` defaults to 'de',
+ * matching the Express default.
+ *
+ * The bespoke "X is required" 400 messages are reproduced in the controller, not
+ * derived from these schemas, so the error body stays byte-identical to Express.
+ */
+
+export const weatherQuerySchema = z.object({
+  lat: z.string().min(1),
+  lng: z.string().min(1),
+  date: z.string().min(1).optional(),
+  lang: z.string().min(1).default('de'),
+});
+export type WeatherQuery = z.infer<typeof weatherQuerySchema>;
+
+/** Detailed weather requires a date (the Express route 400s without it). */
+export const detailedWeatherQuerySchema = weatherQuerySchema.extend({
+  date: z.string().min(1),
+});
+export type DetailedWeatherQuery = z.infer<typeof detailedWeatherQuerySchema>;
+
+export const hourlyEntrySchema = z.object({
+  hour: z.number(),
+  temp: z.number(),
+  precipitation: z.number(),
+  precipitation_probability: z.number(),
+  main: z.string(),
+  wind: z.number(),
+  humidity: z.number(),
+});
+export type HourlyEntry = z.infer<typeof hourlyEntrySchema>;
+
+/**
+ * Weather response DTO. Fields are optional because the Express service emits
+ * different subsets depending on the request type (current / forecast / climate /
+ * detailed) and on error (`{ ..., error: 'no_forecast' }`).
+ */
+export const weatherResultSchema = z.object({
+  temp: z.number(),
+  temp_max: z.number().optional(),
+  temp_min: z.number().optional(),
+  main: z.string(),
+  description: z.string(),
+  type: z.string(),
+  sunrise: z.string().nullable().optional(),
+  sunset: z.string().nullable().optional(),
+  precipitation_sum: z.number().optional(),
+  precipitation_probability_max: z.number().optional(),
+  wind_max: z.number().optional(),
+  hourly: z.array(hourlyEntrySchema).optional(),
+  error: z.string().optional(),
+});
+export type WeatherResult = z.infer<typeof weatherResultSchema>;
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}