// ✅ Good: Uses CSS variables
<div className="bg-primary text-primary-foreground">
<button className="bg-accent hover:bg-accent/90">

// ❌ Bad: Hardcoded colors
<div className="bg-blue-500 text-white">
<button className="bg-green-600 hover:bg-green-700">

/* global.css */
:root {
  --background: 0 0% 100%;  /* White */
  --foreground: 222 47% 11%;  /* Dark text */
}

.dark {
  --background: 224 71% 4%;  /* Dark bg */
  --foreground: 213 31% 91%;  /* Light text */
}

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  {/* 1 column mobile, 2 tablet, 3 desktop */}
</div>

// All interactive elements must be keyboard accessible
<button onClick={handleClick}>Click Me</button>  ✅
<div onClick={handleClick}>Click Me</div>        ❌

button:focus-visible {
  outline: 2px solid hsl(var(--primary));
  outline-offset: 2px;
}

<img src="/logo.png" alt="ProductReady Logo" />

✅ <nav>, <main>, <article>, <button>
❌ <div className="nav">, <div onClick={...}>

// src/lib/demo.ts
export function isDemoMode(searchParams?: URLSearchParams): boolean {
  return searchParams?.get('demo') === '1';
}

// In tRPC router
export const tasksRouter = createTRPCRouter({
  list: publicProcedure
    .input(z.object({ demo: z.boolean().optional() }))
    .query(async ({ ctx, input }) => {
      if (input.demo) {
        return { tasks: getDemoTasks() };  // Mock data
      }
      
      return { tasks: await ctx.db.select().from(tasks) };
    }),
});

/**
 * Creates a new task with AI-generated description
 * @param input - Task title and priority
 * @returns Created task with generated description
 * @throws {Error} If AI service is unavailable
 */
export async function createTaskWithAI(
  input: CreateTaskInput
): Promise<Task> {
  const description = await generateDescription(input.title);
  return db.insert(tasks).values({ ...input, description });
}

# Check for updates
pnpm outdated

# Update interactive
pnpm update -i

# Test after updating
pnpm typecheck
pnpm lint
pnpm test
pnpm build

# Check for vulnerabilities
pnpm audit

# Fix automatically
pnpm audit --fix

// ✅ Good: Full type safety
interface CreateTaskInput {
  title: string;
  description?: string;
  priority: 'low' | 'medium' | 'high' | 'urgent';
}

function createTask(input: CreateTaskInput): Promise<Task> {
  // TypeScript knows exactly what input contains
  return db.insert(tasks).values(input).returning();
}

// ❌ Bad: Using `any` loses all safety
function createTask(input: any) {
  // No idea what input contains - errors at runtime!
  return db.insert(tasks).values(input);
}

import { z } from 'zod';

// Define schema
const CreateTaskSchema = z.object({
  title: z.string().min(1).max(255),
  description: z.string().optional(),
  priority: z.enum(['low', 'medium', 'high', 'urgent']).default('medium'),
});

// Use in tRPC
export const tasksRouter = createTRPCRouter({
  create: protectedProcedure
    .input(CreateTaskSchema)  // ✅ Validates input
    .mutation(async ({ input }) => {
      // input is guaranteed valid here
      return db.insert(tasks).values(input);
    }),
});

// Database layer (PO) - Never expose directly!
const userPO = await db.query.users.findFirst({ 
  where: eq(users.id, userId) 
});
// Contains: passwordHash, stripeCustomerId, etc.

// API layer (DTO) - Validated input
const CreateUserDTO = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  name: z.string(),
});

// UI layer (VO) - Safe to return to frontend
interface UserVO {
  id: string;
  email: string;
  name: string;
  avatar: string | null;
  createdAt: string;  // ISO string, not Date object
}

// Transform PO → VO before returning
function toUserVO(po: UserPO): UserVO {
  return {
    id: po.id,
    email: po.email,
    name: po.name,
    avatar: po.image,
    createdAt: po.createdAt.toISOString(),
  };
}

// ✅ Always use protectedProcedure for sensitive operations
export const tasksRouter = createTRPCRouter({
  delete: protectedProcedure  // Requires authentication
    .input(z.object({ id: z.number() }))
    .mutation(async ({ ctx, input }) => {
      // ctx.session.user is guaranteed to exist
      const userId = ctx.session.user.id;
      
      // ✅ Check ownership before deleting
      const task = await db.query.tasks.findFirst({
        where: eq(tasks.id, input.id),
      });
      
      if (!task || task.userId !== userId) {
        throw new Error('Not authorized');
      }
      
      await db.delete(tasks).where(eq(tasks.id, input.id));
    }),
});

# ✅ Good: Use .env files (git ignored)
PG_DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="..."

# ❌ Bad: Hardcoded in code
const secret = "super-secret-key-123";  // NEVER DO THIS!

# ✅ Available in browser
NEXT_PUBLIC_APP_NAME="ProductReady"

# ✅ Server-only (secure)
PG_DATABASE_URL="postgresql://..."
STRIPE_SECRET_KEY="sk_live_..."

// ❌ Bad: N+1 query (1 + N queries)
const tasks = await db.select().from(tasks);
for (const task of tasks) {
  const user = await db.select().from(users)
    .where(eq(users.id, task.userId));  // N queries!
}

// ✅ Good: Single query with join
const tasksWithUsers = await db
  .select({
    task: tasks,
    user: users,
  })
  .from(tasks)
  .leftJoin(users, eq(tasks.userId, users.id));

export const tasksRouter = createTRPCRouter({
  list: protectedProcedure
    .input(z.object({
      page: z.number().min(1).default(1),
      limit: z.number().min(1).max(100).default(20),
    }))
    .query(async ({ ctx, input }) => {
      const offset = (input.page - 1) * input.limit;
      
      const tasks = await ctx.db
        .select()
        .from(tasks)
        .limit(input.limit)
        .offset(offset);
      
      return { tasks, page: input.page, limit: input.limit };
    }),
});

# Neon - use port 6543 (pooled) instead of 5432
PG_DATABASE_URL="postgresql://user:pass@host:6543/db"

# Supabase - use "connection pooling" string
PG_DATABASE_URL="postgresql://...pooler.supabase.com:6543/..."

// tests/e2e/auth.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Authentication', () => {
  test('user can sign up', async ({ page }) => {
    await page.goto('/signup');
    
    await page.fill('input[name="email"]', 'test@example.com');
    await page.fill('input[name="password"]', 'password123');
    await page.fill('input[name="name"]', 'Test User');
    
    await page.click('button[type="submit"]');
    
    // Should redirect to dashboard
    await expect(page).toHaveURL('/dashboard');
  });
});

pnpm test:e2e       # Headless
pnpm test:e2e:ui    # Interactive mode

// src/lib/utils.test.ts
import { describe, it, expect } from 'vitest';
import { formatCurrency } from './utils';

describe('formatCurrency', () => {
  it('formats USD correctly', () => {
    expect(formatCurrency(1000, 'USD')).toBe('$1,000.00');
  });
  
  it('handles zero', () => {
    expect(formatCurrency(0, 'USD')).toBe('$0.00');
  });
});

# Format and lint
pnpm lint

# Auto-fix issues
pnpm lint --write

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

// ✅ Good: Single responsibility
function TaskCard({ task }: { task: Task }) {
  return (
    <div className="card">
      <h3>{task.title}</h3>
      <p>{task.description}</p>
    </div>
  );
}

function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <div className="grid gap-4">
      {tasks.map(task => <TaskCard key={task.id} task={task} />)}
    </div>
  );
}

// ❌ Bad: Too many responsibilities
function TaskPage() {
  // Fetching, filtering, sorting, rendering all in one component
  // 500 lines of code...
}

// src/app/api/health/route.ts
export async function GET() {
  return Response.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    service: 'productready',
    version: process.env.VERSION || 'unknown',
    buildNumber: process.env.NEXT_PUBLIC_BUILD_NUMBER || '0',
  });
}

// src/app/layout.tsx
import * as Sentry from '@sentry/nextjs';

if (process.env.NODE_ENV === 'production') {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    tracesSampleRate: 0.1,
  });
}

/**
 * Creates a new task with AI-generated description
 * @param input - Task title and priority
 * @returns Created task with generated description
 * @throws {Error} If AI service is unavailable
 */
export async function createTaskWithAI(
  input: CreateTaskInput
): Promise<Task> {
  const description = await generateDescription(input.title);
  return db.insert(tasks).values({ ...input, description });
}

# Check for updates
pnpm outdated

# Update interactive
pnpm update -i

# Test after updating
pnpm typecheck
pnpm lint
pnpm test
pnpm build

# Check for vulnerabilities
pnpm audit

# Fix automatically
pnpm audit --fix

// src/lib/demo.ts
export function isDemoMode(searchParams?: URLSearchParams): boolean {
  return searchParams?.get('demo') === '1';
}

// In tRPC router
export const tasksRouter = createTRPCRouter({
  list: publicProcedure
    .input(z.object({ demo: z.boolean().optional() }))
    .query(async ({ ctx, input }) => {
      if (input.demo) {
        return { tasks: getDemoTasks() };  // Mock data
      }
      
      return { tasks: await ctx.db.select().from(tasks) };
    }),
});