Phase 0 — NestJS + Zod foundation harness (F1–F8) (#1050)

Co-hosted NestJS app behind the existing Express server via a strangler-fig dispatcher, sharing the same better-sqlite3 connection and JWT httpOnly cookie. Additive and dormant: default routing stays on Express, Nest only serves its own /api/_nest diagnostics until a module opts in.

F1 @trek/shared Zod contract package; F2 Nest bootstrap co-hosted (fall-through, single Dockerfile/port); F3 shared better-sqlite3 provider; F4 JWT cookie auth guard (+ @CurrentUser, admin guard); F5 Zod validation pipe + error-envelope parity; F6 Nest test + coverage gates; F7 per-prefix strangler toggle (env, default Express); F8 CI build/typecheck/test/coverage.

Remaining F4/F6/F8 checklist items (trip-access + permission levels + MFA policy, e2e harness/seed + 80% gate, Nest↔Express parity test, Playwright PR-comment workflow) are tracked on the first consuming module cards (L1/A1/C1).

shared/src/common/pagination.schema.ts

@@ -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>;

shared/src/common/primitives.schema.spec.ts

@@ -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);
+  });
+});

shared/src/common/primitives.schema.ts

@@ -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 });

shared/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @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';