proagents 1.0.0

package/proagents/examples/fullstack-nextjs/complete-conversation.md

@@ -0,0 +1,604 @@
+# Complete Conversation: Next.js Settings Feature
+
+A full walkthrough of building a settings page with API in a Next.js application.
+
+---
+
+## Feature Request
+
+**User:** I need to add a user settings page where users can update their profile, change notification preferences, and manage their account. It should have an API backend.
+
+---
+
+## Phase 0: Initialization
+
+**AI:** I'll help you build a comprehensive settings feature. Let me start by analyzing your existing codebase.
+
+```
+Starting ProAgents workflow...
+Mode: Full Workflow
+Feature: User Settings Page with API
+Branch: feature/user-settings
+```
+
+---
+
+## Phase 1: Codebase Analysis
+
+**AI:** I've analyzed your Next.js project. Here's what I found:
+
+### Project Structure
+```
+app/
+├── (auth)/
+│   ├── dashboard/
+│   │   └── page.tsx
+│   └── layout.tsx
+├── api/
+│   └── users/
+│       └── route.ts
+├── layout.tsx
+└── page.tsx
+lib/
+├── db.ts              # Prisma client
+├── auth.ts            # NextAuth config
+└── validations/
+    └── user.ts        # Zod schemas
+components/
+├── ui/                # shadcn/ui components
+└── forms/
+prisma/
+└── schema.prisma
+```
+
+### Patterns Detected
+- **Framework:** Next.js 14 with App Router
+- **Database:** Prisma with PostgreSQL
+- **Auth:** NextAuth.js with JWT strategy
+- **UI:** shadcn/ui components with Tailwind
+- **Validation:** Zod schemas
+- **State:** React Query for server state
+
+### Existing Conventions
+- API routes use typed request/response
+- Forms use react-hook-form with Zod
+- All routes under `(auth)` require authentication
+
+**Checkpoint: Analysis Complete**
+Do you want to proceed with these patterns? [Yes/Modify]
+
+**User:** Yes, proceed.
+
+---
+
+## Phase 2: Requirements
+
+**AI:** Let me clarify the requirements for the settings feature.
+
+### Feature Requirements
+
+**1. Profile Settings**
+- Update display name
+- Update avatar (upload)
+- Update bio/description
+
+**2. Notification Preferences**
+- Email notifications toggle
+- Push notifications toggle
+- Notification frequency (immediate/daily/weekly)
+
+**3. Account Settings**
+- Change email (with verification)
+- Change password
+- Delete account (with confirmation)
+
+### Technical Requirements
+- All operations require authentication
+- Form validation with Zod
+- Optimistic updates where appropriate
+- Proper error handling
+
+**User:** Looks good, but also add a timezone selector in profile settings.
+
+**AI:** Added timezone selector to profile settings.
+
+---
+
+## Phase 3: Design
+
+**AI:** Based on your existing UI patterns, here's the design specification:
+
+### Page Layout
+```
+/settings
+├── /settings/profile      # Profile settings
+├── /settings/notifications # Notification preferences
+└── /settings/account      # Account management
+```
+
+### Component Structure
+```tsx
+// Settings layout with sidebar navigation
+<SettingsLayout>
+  <SettingsSidebar />
+  <SettingsContent>
+    {children}
+  </SettingsContent>
+</SettingsLayout>
+```
+
+### UI Components (using existing shadcn/ui)
+- Card for each settings section
+- Form with Input, Select, Switch components
+- Button for actions
+- AlertDialog for destructive actions
+- Toast for feedback
+
+**Checkpoint: Design Complete**
+Ready to proceed with implementation? [Yes/Modify]
+
+**User:** Yes.
+
+---
+
+## Phase 4: Implementation Plan
+
+**AI:** Here's the implementation plan:
+
+### Database Changes
+```prisma
+// Add to schema.prisma
+model UserSettings {
+  id                    String   @id @default(cuid())
+  userId                String   @unique
+  user                  User     @relation(fields: [userId], references: [id])
+  timezone              String   @default("UTC")
+  emailNotifications    Boolean  @default(true)
+  pushNotifications     Boolean  @default(false)
+  notificationFrequency String   @default("immediate")
+  createdAt             DateTime @default(now())
+  updatedAt             DateTime @updatedAt
+}
+```
+
+### Files to Create
+1. `prisma/migrations/xxx_add_user_settings.sql`
+2. `lib/validations/settings.ts` - Zod schemas
+3. `app/api/settings/route.ts` - GET/PATCH settings
+4. `app/api/settings/password/route.ts` - Change password
+5. `app/api/settings/account/route.ts` - Delete account
+6. `app/(auth)/settings/layout.tsx` - Settings layout
+7. `app/(auth)/settings/page.tsx` - Redirect to profile
+8. `app/(auth)/settings/profile/page.tsx`
+9. `app/(auth)/settings/notifications/page.tsx`
+10. `app/(auth)/settings/account/page.tsx`
+11. `components/settings/SettingsSidebar.tsx`
+12. `components/settings/ProfileForm.tsx`
+13. `components/settings/NotificationsForm.tsx`
+14. `components/settings/AccountSettings.tsx`
+
+### Implementation Order
+1. Database schema + migration
+2. Validation schemas
+3. API routes
+4. Layout and navigation
+5. Individual settings pages
+6. Forms and components
+
+---
+
+## Phase 5: Implementation
+
+**AI:** Starting implementation. Creating branch `feature/user-settings`.
+
+### Step 1: Database Schema
+
+```prisma
+// prisma/schema.prisma - additions
+model UserSettings {
+  id                    String   @id @default(cuid())
+  userId                String   @unique
+  user                  User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  timezone              String   @default("UTC")
+  emailNotifications    Boolean  @default(true)
+  pushNotifications     Boolean  @default(false)
+  notificationFrequency String   @default("immediate")
+  createdAt             DateTime @default(now())
+  updatedAt             DateTime @updatedAt
+}
+```
+
+```bash
+npx prisma migrate dev --name add_user_settings
+```
+
+### Step 2: Validation Schemas
+
+```typescript
+// lib/validations/settings.ts
+import { z } from 'zod';
+
+export const profileSchema = z.object({
+  name: z.string().min(2).max(50),
+  bio: z.string().max(500).optional(),
+  timezone: z.string(),
+});
+
+export const notificationsSchema = z.object({
+  emailNotifications: z.boolean(),
+  pushNotifications: z.boolean(),
+  notificationFrequency: z.enum(['immediate', 'daily', 'weekly']),
+});
+
+export const passwordSchema = z.object({
+  currentPassword: z.string().min(8),
+  newPassword: z.string().min(8),
+  confirmPassword: z.string().min(8),
+}).refine((data) => data.newPassword === data.confirmPassword, {
+  message: "Passwords don't match",
+  path: ["confirmPassword"],
+});
+
+export const deleteAccountSchema = z.object({
+  confirmation: z.literal('DELETE'),
+});
+```
+
+### Step 3: API Routes
+
+```typescript
+// app/api/settings/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getServerSession } from 'next-auth';
+import { authOptions } from '@/lib/auth';
+import { db } from '@/lib/db';
+import { profileSchema, notificationsSchema } from '@/lib/validations/settings';
+
+export async function GET(req: NextRequest) {
+  try {
+    const session = await getServerSession(authOptions);
+    if (!session?.user?.id) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const settings = await db.userSettings.findUnique({
+      where: { userId: session.user.id },
+    });
+
+    // Create default settings if none exist
+    if (!settings) {
+      const newSettings = await db.userSettings.create({
+        data: { userId: session.user.id },
+      });
+      return NextResponse.json({ data: newSettings });
+    }
+
+    return NextResponse.json({ data: settings });
+  } catch (error) {
+    return NextResponse.json({ error: 'Failed to fetch settings' }, { status: 500 });
+  }
+}
+
+export async function PATCH(req: NextRequest) {
+  try {
+    const session = await getServerSession(authOptions);
+    if (!session?.user?.id) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const body = await req.json();
+    const { type, ...data } = body;
+
+    let validatedData;
+    if (type === 'profile') {
+      validatedData = profileSchema.parse(data);
+      await db.user.update({
+        where: { id: session.user.id },
+        data: { name: validatedData.name },
+      });
+    } else if (type === 'notifications') {
+      validatedData = notificationsSchema.parse(data);
+    }
+
+    const settings = await db.userSettings.upsert({
+      where: { userId: session.user.id },
+      update: validatedData,
+      create: { userId: session.user.id, ...validatedData },
+    });
+
+    return NextResponse.json({ data: settings });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: error.errors }, { status: 400 });
+    }
+    return NextResponse.json({ error: 'Failed to update settings' }, { status: 500 });
+  }
+}
+```
+
+### Step 4: Settings Layout
+
+```tsx
+// app/(auth)/settings/layout.tsx
+import { SettingsSidebar } from '@/components/settings/SettingsSidebar';
+
+export default function SettingsLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="container max-w-6xl py-8">
+      <h1 className="text-3xl font-bold mb-8">Settings</h1>
+      <div className="flex gap-8">
+        <SettingsSidebar />
+        <div className="flex-1">{children}</div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Step 5: Profile Page
+
+```tsx
+// app/(auth)/settings/profile/page.tsx
+import { ProfileForm } from '@/components/settings/ProfileForm';
+import { getServerSession } from 'next-auth';
+import { authOptions } from '@/lib/auth';
+import { db } from '@/lib/db';
+
+export default async function ProfileSettingsPage() {
+  const session = await getServerSession(authOptions);
+  const user = await db.user.findUnique({
+    where: { id: session?.user?.id },
+    include: { settings: true },
+  });
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h2 className="text-xl font-semibold">Profile</h2>
+        <p className="text-muted-foreground">
+          Manage your public profile information.
+        </p>
+      </div>
+      <ProfileForm user={user} />
+    </div>
+  );
+}
+```
+
+[Implementation continues for all components...]
+
+---
+
+## Phase 6: Testing
+
+**AI:** Creating tests for the settings feature.
+
+### API Route Tests
+
+```typescript
+// __tests__/api/settings.test.ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { GET, PATCH } from '@/app/api/settings/route';
+import { NextRequest } from 'next/server';
+
+vi.mock('next-auth', () => ({
+  getServerSession: vi.fn(),
+}));
+
+vi.mock('@/lib/db', () => ({
+  db: {
+    userSettings: {
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      upsert: vi.fn(),
+    },
+    user: {
+      update: vi.fn(),
+    },
+  },
+}));
+
+describe('Settings API', () => {
+  describe('GET /api/settings', () => {
+    it('returns 401 when not authenticated', async () => {
+      const { getServerSession } = await import('next-auth');
+      vi.mocked(getServerSession).mockResolvedValue(null);
+
+      const req = new NextRequest('http://localhost/api/settings');
+      const res = await GET(req);
+
+      expect(res.status).toBe(401);
+    });
+
+    it('returns user settings when authenticated', async () => {
+      const { getServerSession } = await import('next-auth');
+      vi.mocked(getServerSession).mockResolvedValue({
+        user: { id: 'user-1' },
+      });
+
+      const { db } = await import('@/lib/db');
+      vi.mocked(db.userSettings.findUnique).mockResolvedValue({
+        id: 'settings-1',
+        userId: 'user-1',
+        timezone: 'America/New_York',
+        emailNotifications: true,
+        pushNotifications: false,
+        notificationFrequency: 'daily',
+      });
+
+      const req = new NextRequest('http://localhost/api/settings');
+      const res = await GET(req);
+      const data = await res.json();
+
+      expect(res.status).toBe(200);
+      expect(data.data.timezone).toBe('America/New_York');
+    });
+  });
+
+  describe('PATCH /api/settings', () => {
+    it('validates notification settings', async () => {
+      const { getServerSession } = await import('next-auth');
+      vi.mocked(getServerSession).mockResolvedValue({
+        user: { id: 'user-1' },
+      });
+
+      const req = new NextRequest('http://localhost/api/settings', {
+        method: 'PATCH',
+        body: JSON.stringify({
+          type: 'notifications',
+          emailNotifications: 'invalid', // Should be boolean
+        }),
+      });
+
+      const res = await PATCH(req);
+      expect(res.status).toBe(400);
+    });
+  });
+});
+```
+
+### Component Tests
+
+```typescript
+// __tests__/components/ProfileForm.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ProfileForm } from '@/components/settings/ProfileForm';
+
+describe('ProfileForm', () => {
+  const mockUser = {
+    id: 'user-1',
+    name: 'John Doe',
+    email: 'john@example.com',
+    settings: {
+      timezone: 'UTC',
+    },
+  };
+
+  it('renders with user data', () => {
+    render(<ProfileForm user={mockUser} />);
+
+    expect(screen.getByDisplayValue('John Doe')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('UTC')).toBeInTheDocument();
+  });
+
+  it('validates required fields', async () => {
+    render(<ProfileForm user={mockUser} />);
+
+    const nameInput = screen.getByLabelText(/name/i);
+    await userEvent.clear(nameInput);
+    await userEvent.click(screen.getByRole('button', { name: /save/i }));
+
+    expect(screen.getByText(/name is required/i)).toBeInTheDocument();
+  });
+});
+```
+
+### E2E Tests
+
+```typescript
+// e2e/settings.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Settings Page', () => {
+  test.beforeEach(async ({ page }) => {
+    // Login before each test
+    await page.goto('/login');
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="password"]', 'password123');
+    await page.click('button[type="submit"]');
+    await page.waitForURL('/dashboard');
+  });
+
+  test('can update profile settings', async ({ page }) => {
+    await page.goto('/settings/profile');
+
+    await page.fill('[name="name"]', 'Updated Name');
+    await page.click('button:has-text("Save")');
+
+    await expect(page.locator('.toast')).toContainText('Settings saved');
+  });
+
+  test('can toggle notification preferences', async ({ page }) => {
+    await page.goto('/settings/notifications');
+
+    const emailToggle = page.locator('[name="emailNotifications"]');
+    await emailToggle.click();
+    await page.click('button:has-text("Save")');
+
+    await expect(page.locator('.toast')).toContainText('Settings saved');
+  });
+});
+```
+
+**Test Results:**
+```
+✓ API tests: 12 passed
+✓ Component tests: 8 passed
+✓ E2E tests: 5 passed
+Coverage: 87%
+```
+
+---
+
+## Phase 7: Documentation
+
+**AI:** Creating documentation for the settings feature.
+
+### API Documentation
+
+```markdown
+## Settings API
+
+### GET /api/settings
+Returns the current user's settings.
+
+**Response:**
+- 200: Settings object
+- 401: Unauthorized
+
+### PATCH /api/settings
+Updates user settings.
+
+**Body:**
+- type: "profile" | "notifications"
+- ...fields based on type
+
+**Response:**
+- 200: Updated settings
+- 400: Validation error
+- 401: Unauthorized
+```
+
+---
+
+## Phase 8: Deployment Preparation
+
+**AI:** Pre-deployment checklist:
+
+- [x] All tests passing
+- [x] Database migration ready
+- [x] Environment variables documented
+- [x] No hardcoded secrets
+- [x] Error handling complete
+- [x] Loading states implemented
+- [x] Mobile responsive
+
+**Ready for deployment.**
+
+---
+
+## Summary
+
+**Feature Complete:** User Settings Page with API
+
+**Files Created:** 15
+**Tests Added:** 25
+**Coverage:** 87%
+
+**PR Ready:** `feature/user-settings` → `main`