Merge branch 'main' into codex/milestone-5-beta-docs

Author: tkxkd0159

AGENTS.md

@@ -14,10 +14,10 @@ This is a Next.js App Router project with TypeScript, NextAuth, PostgreSQL, Vite
   - `components/clubs/`: club cards, boards, and book-assignment forms.
   - `components/ui/`: shared primitives (`button`, `input`, `textarea`, `card`, `badge`).
 - `lib/`: business and integration logic.
-  - `lib/auth/`: NextAuth options, session helpers, user persistence, secrets, and e2e auth helpers.
+  - `lib/auth/`: NextAuth options, session helpers, user persistence, and secrets.
   - `lib/books/`: Google Books API integration, description/volume normalization, and repository access.
   - `lib/clubs/`: validation, permissions, presentation helpers, repository access, and domain errors.
-  - `lib/test/fixtures.ts`: shared test fixtures.
+  - `lib/test-harness/`: runtime-safe e2e/test harness helpers, fixtures, and deterministic Google Books mock data.
   - `lib/db.ts`: PostgreSQL connection.
 - `tests/`: Vitest coverage split into `tests/unit/` and `tests/integration/`.
 - `e2e/`: Playwright specs and helpers.
@@ -75,8 +75,7 @@ Always treat these as quality gates for substantial changes:
 
 ## Security & Configuration Tips
 - Keep secrets in `.env.local`; never commit credentials.
-- Required env for the full app flow: `DATABASE_URL`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_BOOKS_API_KEY`, `AUTH_SECRET` (or `NEXTAUTH_SECRET`).
-- Set `NEXTAUTH_URL` in runtime environments to avoid NextAuth callback and URL issues.
+- Required env for the full app flow: `DATABASE_URL`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_BOOKS_API_KEY`, `AUTH_SECRET` (or `NEXTAUTH_SECRET`), and `NEXTAUTH_URL` for production-like or e2e-authenticated runs. `GOOGLE_BOOKS_API_BASE_URL` is optional and intended for test/local upstream overrides.
 - `E2E_BYPASS_AUTH=1` is test-only; do not enable it in normal development or production.
 - `app/api/test/*` routes are intentionally public only under e2e bypass mode; preserve that constraint.
 - Do not edit `.next/`, `node_modules/`, `playwright-report/`, or `test-results/`; these are generated artifacts.

README.md

@@ -17,17 +17,17 @@ GOOGLE_CLIENT_SECRET=...
 GOOGLE_BOOKS_API_KEY=...
 
 DATABASE_URL=postgres://...
-
-RATE_LIMIT_PROVIDER=<redis|upstash>
-UPSTASH_REDIS_REST_URL=...
-UPSTASH_REDIS_REST_TOKEN=...
 ```
 
 Optional:
 
 ```bash
 NEXTAUTH_URL=http://localhost:3000
 NEXTAUTH_SECRET=...
+RATE_LIMIT_PROVIDER=<disabled|memory|redis|upstash>
+RATE_LIMIT_REDIS_URL=redis://...
+UPSTASH_REDIS_REST_URL=...
+UPSTASH_REDIS_REST_TOKEN=...
 ```
 
 Generate a strong secret:
@@ -97,6 +97,8 @@ REMOVE_VOLUME=1
 pnpm dev
 ```
 
+`next dev`, `next build`, and `next start` now validate the required application environment before the app fully boots. Missing or invalid values fail fast with one aggregated error message.
+
 When you run `npm start` or `pnpm start`, a `prestart` hook now verifies that local PostgreSQL is reachable at `localhost:54329` when `DATABASE_URL` targets the local dev database. If it is not running, start it with:
 
 ```bash

app/api/test/auth/route.ts

@@ -1,16 +1,18 @@
 import { NextRequest, NextResponse } from "next/server";
 
-import { E2E_AUTH_COOKIE_NAME } from "@/lib/auth/constants";
-import { isE2EBypassEnabled } from "@/lib/auth/e2e";
+import {
+  E2E_AUTH_COOKIE_NAME,
+  isE2EBypassEnabled,
+} from "@/lib/test-harness/auth";
 import {
   getTestUser,
   seedTestUsers,
-} from "@/lib/test/fixtures";
+} from "@/lib/test-harness/fixtures";
 import {
   E2E_DEFAULT_RETURN_TO,
   TEST_ROUTE_ERROR_MESSAGES,
   isTestUserKey,
-} from "@/lib/test/constants";
+} from "@/lib/test-harness/constants";
 
 export const runtime = "nodejs";
 

app/api/test/club-books/route.ts

@@ -0,0 +1,100 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+
+import { findUserByProviderIdentity } from "@/lib/auth/users";
+import { findBookByGoogleVolumeId } from "@/lib/books/repository";
+import { addBookToClub, removeClubBook } from "@/lib/clubs/repository";
+import {
+  E2E_USER_PROVIDER,
+  isE2EBypassEnabled,
+} from "@/lib/test-harness/auth";
+import {
+  TEST_ROUTE_ERROR_MESSAGES,
+  TEST_USER_KEYS,
+} from "@/lib/test-harness/constants";
+import {
+  TEST_BOOK_VOLUME_ID,
+  seedTestUsers,
+} from "@/lib/test-harness/fixtures";
+
+export const runtime = "nodejs";
+
+const CLUB_BOOK_STATUSES = ["WANT_TO_READ", "READING", "READ"] as const;
+
+const seedClubBookSchema = z.object({
+  kind: z.literal("add-book"),
+  clubId: z.string().min(1),
+  googleVolumeId: z.string().min(1).default(TEST_BOOK_VOLUME_ID),
+  status: z.enum(CLUB_BOOK_STATUSES).default("WANT_TO_READ"),
+  user: z.enum(TEST_USER_KEYS),
+});
+
+const archiveClubBookSchema = z.object({
+  kind: z.literal("remove-book"),
+  clubId: z.string().min(1),
+  clubBookId: z.string().min(1),
+  user: z.enum(TEST_USER_KEYS),
+});
+
+const clubBookPayloadSchema = z.union([
+  seedClubBookSchema,
+  archiveClubBookSchema,
+]);
+
+export async function POST(request: NextRequest) {
+  if (!isE2EBypassEnabled()) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.notAvailable },
+      { status: 404 },
+    );
+  }
+
+  const parsedBody = clubBookPayloadSchema.safeParse(
+    await request.json().catch(() => null),
+  );
+  if (!parsedBody.success) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.invalidSeedPayload },
+      { status: 400 },
+    );
+  }
+
+  await seedTestUsers();
+  const user = await findUserByProviderIdentity(
+    E2E_USER_PROVIDER,
+    parsedBody.data.user,
+  );
+  if (!user) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.unknownTestUser },
+      { status: 400 },
+    );
+  }
+
+  if (parsedBody.data.kind === "remove-book") {
+    await removeClubBook({
+      clubId: parsedBody.data.clubId,
+      clubBookId: parsedBody.data.clubBookId,
+      removedById: user.id,
+    });
+
+    return NextResponse.json({ ok: true });
+  }
+
+  const book = await findBookByGoogleVolumeId(parsedBody.data.googleVolumeId);
+  if (!book) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.invalidSeedPayload },
+      { status: 400 },
+    );
+  }
+
+  const clubBook = await addBookToClub({
+    clubId: parsedBody.data.clubId,
+    bookId: book.id,
+    addedById: user.id,
+    status: parsedBody.data.status,
+  });
+
+  return NextResponse.json({ ok: true, clubBookId: clubBook.id });
+}

app/api/test/reset/route.ts

@@ -1,9 +1,9 @@
 import { NextResponse } from "next/server";
 
-import { isE2EBypassEnabled } from "@/lib/auth/e2e";
 import { resetMemoryMutationRateLimitStore } from "@/lib/rate-limit/mutation";
-import { resetTestDatabase } from "@/lib/test/fixtures";
-import { TEST_ROUTE_ERROR_MESSAGES } from "@/lib/test/constants";
+import { isE2EBypassEnabled } from "@/lib/test-harness/auth";
+import { TEST_ROUTE_ERROR_MESSAGES } from "@/lib/test-harness/constants";
+import { resetTestDatabase } from "@/lib/test-harness/fixtures";
 
 export const runtime = "nodejs";
 

app/api/test/reviews/route.ts

@@ -0,0 +1,79 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+
+import { findUserByProviderIdentity } from "@/lib/auth/users";
+import { findBookByGoogleVolumeId } from "@/lib/books/repository";
+import { upsertReview } from "@/lib/reviews/repository";
+import { parseReviewBody, parseReviewRating, parseReviewTitle } from "@/lib/reviews/validation";
+import {
+  E2E_USER_PROVIDER,
+  isE2EBypassEnabled,
+} from "@/lib/test-harness/auth";
+import {
+  TEST_ROUTE_ERROR_MESSAGES,
+  TEST_USER_KEYS,
+} from "@/lib/test-harness/constants";
+import {
+  TEST_BOOK_VOLUME_ID,
+  seedTestUsers,
+} from "@/lib/test-harness/fixtures";
+
+export const runtime = "nodejs";
+
+const seedReviewSchema = z.object({
+  kind: z.literal("upsert"),
+  googleVolumeId: z.string().min(1).default(TEST_BOOK_VOLUME_ID),
+  user: z.enum(TEST_USER_KEYS),
+  rating: z.number().min(0.5).max(5),
+  title: z.string().max(120).default(""),
+  body: z.string().max(5000).default(""),
+});
+
+export async function POST(request: NextRequest) {
+  if (!isE2EBypassEnabled()) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.notAvailable },
+      { status: 404 },
+    );
+  }
+
+  const parsedBody = seedReviewSchema.safeParse(
+    await request.json().catch(() => null),
+  );
+  if (!parsedBody.success) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.invalidSeedPayload },
+      { status: 400 },
+    );
+  }
+
+  await seedTestUsers();
+  const user = await findUserByProviderIdentity(
+    E2E_USER_PROVIDER,
+    parsedBody.data.user,
+  );
+  if (!user) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.unknownTestUser },
+      { status: 400 },
+    );
+  }
+
+  const book = await findBookByGoogleVolumeId(parsedBody.data.googleVolumeId);
+  if (!book) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.invalidSeedPayload },
+      { status: 400 },
+    );
+  }
+
+  await upsertReview({
+    userId: user.id,
+    bookId: book.id,
+    rating: parseReviewRating(parsedBody.data.rating),
+    title: parseReviewTitle(parsedBody.data.title),
+    body: parseReviewBody(parsedBody.data.body),
+  });
+
+  return NextResponse.json({ ok: true });
+}

app/api/test/shelves/route.ts

@@ -0,0 +1,74 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+
+import { findUserByProviderIdentity } from "@/lib/auth/users";
+import { findBookByGoogleVolumeId } from "@/lib/books/repository";
+import { addBookToShelf } from "@/lib/shelves/repository";
+import {
+  E2E_USER_PROVIDER,
+  isE2EBypassEnabled,
+} from "@/lib/test-harness/auth";
+import {
+  TEST_ROUTE_ERROR_MESSAGES,
+  TEST_USER_KEYS,
+} from "@/lib/test-harness/constants";
+import {
+  TEST_BOOK_VOLUME_ID,
+  seedTestUsers,
+} from "@/lib/test-harness/fixtures";
+
+export const runtime = "nodejs";
+
+const seedShelfBookSchema = z.object({
+  kind: z.literal("add-book"),
+  shelfId: z.string().min(1),
+  user: z.enum(TEST_USER_KEYS),
+  googleVolumeId: z.string().min(1).default(TEST_BOOK_VOLUME_ID),
+});
+
+export async function POST(request: NextRequest) {
+  if (!isE2EBypassEnabled()) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.notAvailable },
+      { status: 404 },
+    );
+  }
+
+  const parsedBody = seedShelfBookSchema.safeParse(
+    await request.json().catch(() => null),
+  );
+  if (!parsedBody.success) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.invalidSeedPayload },
+      { status: 400 },
+    );
+  }
+
+  await seedTestUsers();
+  const user = await findUserByProviderIdentity(
+    E2E_USER_PROVIDER,
+    parsedBody.data.user,
+  );
+  if (!user) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.unknownTestUser },
+      { status: 400 },
+    );
+  }
+
+  const book = await findBookByGoogleVolumeId(parsedBody.data.googleVolumeId);
+  if (!book) {
+    return NextResponse.json(
+      { error: TEST_ROUTE_ERROR_MESSAGES.invalidSeedPayload },
+      { status: 400 },
+    );
+  }
+
+  await addBookToShelf({
+    shelfId: parsedBody.data.shelfId,
+    bookId: book.id,
+    addedById: user.id,
+  });
+
+  return NextResponse.json({ ok: true });
+}