@levironexe/architect 0.1.0

package/skills/patterns/nextauth.skill.yaml

@@ -0,0 +1,308 @@
+schema_version: "2.0.0"
+id: nextauth
+name: "NextAuth.js / Auth.js"
+version: "2.0.0"
+description: "Self-hosted authentication with NextAuth.js v4 / Auth.js v5 — provider configuration, JWT/database session strategies, role-based access, and middleware route protection."
+category: pattern
+language: javascript
+frameworks:
+  - next-auth
+dependencies:
+  none:
+    - "@clerk/nextjs"
+    - "@supabase/ssr"
+    - lucia
+detection:
+  dependencies:
+    any:
+      - next-auth
+      - "@auth/nextjs"
+      - "@auth/core"
+  source_indicators:
+    - "NextAuth("
+    - "authOptions"
+    - "getServerSession"
+    - "useSession"
+    - "SessionProvider"
+    - "auth()"
+structure:
+  required_dirs:
+    - path: app/api/auth
+      purpose: "NextAuth.js catch-all route directory — must contain [...nextauth]/route.ts which exports both GET and POST handlers. All sign-in, sign-out, OAuth callbacks, CSRF protection, and provider redirects run through this single route. Never add business logic here."
+  recommended_dirs:
+    - path: src/lib
+      purpose: "Single authOptions export in auth.ts — provider configuration, session strategy, adapter wiring, jwt and session callbacks. Imported by the route handler, getServerSession calls, and middleware. Keeping authOptions in one file ensures all tokens are signed with the same secret."
+    - path: components
+      purpose: "Client Component wrappers that depend on next-auth/react hooks — primarily a Providers.tsx that wraps SessionProvider so the root layout stays a Server Component."
+separation:
+  rules:
+    - concern: route_handler
+      belongs_in: app/api/auth
+      rule_text: "Create the NextAuth route handler at app/api/auth/[...nextauth]/route.ts. Import authOptions from src/lib/auth.ts — never inline provider config in the route file. The handler must export both GET and POST or sign-in and CSRF flows will break."
+      example: |
+        // app/api/auth/[...nextauth]/route.ts
+        import NextAuth from 'next-auth';
+        import { authOptions } from '@/lib/auth';
+
+        const handler = NextAuth(authOptions);
+        export { handler as GET, handler as POST };
+      indicators:
+        - "NextAuth("
+        - "[...nextauth]"
+        - "handler as GET"
+        - "handler as POST"
+    - concern: auth_config
+      belongs_in: src/lib
+      rule_text: "Define all providers, callbacks, adapter, and session strategy in src/lib/auth.ts as a single exported NextAuthOptions object. Every file that needs session data imports authOptions from this one location. The jwt and session callbacks must both be present to persist custom fields like user.id or user.role."
+      example: |
+        // src/lib/auth.ts — single authoritative NextAuth configuration
+        import { type NextAuthOptions } from 'next-auth';
+        import GithubProvider from 'next-auth/providers/github';
+        import { PrismaAdapter } from '@auth/prisma-adapter';
+        import { prisma } from '@/lib/db';
+
+        export const authOptions: NextAuthOptions = {
+          adapter: PrismaAdapter(prisma),
+          providers: [
+            GithubProvider({
+              clientId: process.env.GITHUB_ID!,
+              clientSecret: process.env.GITHUB_SECRET!,
+            }),
+          ],
+          session: { strategy: 'database' },
+          secret: process.env.NEXTAUTH_SECRET,
+          callbacks: {
+            // Thread custom fields from DB user into session
+            session({ session, user }) {
+              if (session.user) {
+                session.user.id = user.id;
+                (session.user as any).role = (user as any).role;
+              }
+              return session;
+            },
+          },
+        };
+      indicators:
+        - "authOptions"
+        - "NextAuthOptions"
+        - "providers:"
+        - "callbacks:"
+        - "NEXTAUTH_SECRET"
+    - concern: session_access
+      belongs_in: app
+      rule_text: "In Server Components and API routes, use getServerSession(authOptions) to read the session. In Client Components, use useSession() from next-auth/react. Never read session cookies or JWT tokens manually — getServerSession reads the cookie but handles decryption and expiry."
+      example: |
+        // Server Component — no loading state, data available on first render
+        import { getServerSession } from 'next-auth';
+        import { authOptions } from '@/lib/auth';
+        import { redirect } from 'next/navigation';
+
+        export default async function ProtectedPage() {
+          const session = await getServerSession(authOptions);
+          if (!session) redirect('/api/auth/signin');
+          return <Dashboard user={session.user} />;
+        }
+
+        // Client Component — shows loading state during hydration
+        'use client';
+        import { useSession } from 'next-auth/react';
+        export function UserMenu() {
+          const { data: session, status } = useSession();
+          if (status === 'loading') return <Spinner />;
+          if (!session) return <SignInButton />;
+          return <UserAvatar user={session.user} />;
+        }
+      indicators:
+        - "getServerSession"
+        - "useSession()"
+        - "from 'next-auth/react'"
+        - "authOptions"
+    - concern: middleware_protection
+      belongs_in: middleware.ts
+      rule_text: "Export next-auth/middleware as the default export to protect matching routes. Configure the matcher pattern to exclude /api/auth (the NextAuth handler itself), static assets, and public pages. Use the authorized callback in authOptions for role-based access control."
+      example: |
+        // middleware.ts — blanket protection for dashboard and protected API routes
+        export { default } from 'next-auth/middleware';
+
+        export const config = {
+          matcher: [
+            '/dashboard/:path*',
+            '/admin/:path*',
+            '/api/protected/:path*',
+            // Does NOT match: /api/auth (NextAuth handler), /sign-in, static files
+          ],
+        };
+
+        // For role-based access, add authorized callback in authOptions:
+        // callbacks: {
+        //   authorized({ token, req }) {
+        //     if (req.nextUrl.pathname.startsWith('/admin')) return token?.role === 'admin';
+        //     return !!token;
+        //   },
+        // }
+      indicators:
+        - "next-auth/middleware"
+        - "matcher:"
+        - "authorized("
+    - concern: session_provider
+      belongs_in: components
+      rule_text: "Wrap SessionProvider in a dedicated 'use client' component so the root layout stays a Server Component. Pass the server-fetched session as a prop to SessionProvider to eliminate the loading flicker that occurs when SessionProvider fetches the session client-side."
+      example: |
+        // components/providers.tsx — isolates the 'use client' boundary
+        'use client';
+        import { SessionProvider } from 'next-auth/react';
+        import type { Session } from 'next-auth';
+
+        export function Providers({
+          children,
+          session,
+        }: {
+          children: React.ReactNode;
+          session: Session | null;
+        }) {
+          return <SessionProvider session={session}>{children}</SessionProvider>;
+        }
+
+        // app/layout.tsx — Server Component, fetches session for SSR hydration
+        import { getServerSession } from 'next-auth';
+        import { authOptions } from '@/lib/auth';
+        import { Providers } from '@/components/providers';
+
+        export default async function RootLayout({ children }: { children: React.ReactNode }) {
+          const session = await getServerSession(authOptions);
+          return (
+            <html lang="en">
+              <body>
+                <Providers session={session}>{children}</Providers>
+              </body>
+            </html>
+          );
+        }
+      indicators:
+        - "SessionProvider"
+        - "session={session}"
+        - "from 'next-auth/react'"
+patterns:
+  data_flow:
+    direction: "Request → Middleware (withAuth) → Server Component (getServerSession) → Service → DB"
+    rules:
+      - "Middleware protects routes before any rendering — pages don't need to re-check for middleware-covered paths."
+      - "Server Components call getServerSession(authOptions) — reads the encrypted cookie without an extra network call."
+      - "Client Components call useSession() — reads from SessionProvider context already in the page, zero extra requests."
+      - "authOptions is defined once in src/lib/auth.ts — imported by route handler, middleware, and all session accessors so they all use the same secret and config."
+      - "Custom session fields (user.id, user.role) must flow through both jwt callback (token enrichment) and session callback (token → session mapping)."
+      - "Database sessions (strategy: 'database') store the session in your DB via the adapter — JWT sessions store everything in the encrypted cookie."
+  error_handling:
+    recommended: "Check if session is null before accessing session.user properties — getServerSession() returns null for unauthenticated requests, not an error. Redirect to /api/auth/signin to let NextAuth handle the sign-in flow rather than a custom page."
+  naming:
+    config: "src/lib/auth.ts — single authOptions export, imported by all session consumers"
+    route_handler: "app/api/auth/[...nextauth]/route.ts — exports GET and POST"
+    session_provider: "components/providers.tsx — 'use client' wrapper for SessionProvider"
+    session_helper: "getServerSession(authOptions) in Server Components; useSession() in Client Components"
+anti_patterns:
+  - id: missing_secret
+    severity: critical
+    description: "Running NextAuth without NEXTAUTH_SECRET set to a strong random value. In development, NextAuth uses an insecure default and issues a warning. In production, it throws a hard startup error. Without a strong secret, session tokens can be forged by brute-force."
+    bad_example: |
+      # .env — weak or missing secret
+      NEXTAUTH_SECRET=secret         # too short, too predictable
+      # Or: NEXTAUTH_SECRET not set at all — uses insecure default in dev
+    good_example: |
+      # .env.local — strong random secret, 32+ characters
+      NEXTAUTH_SECRET=your-32-char-or-longer-random-secret-here
+      # Generate with: openssl rand -base64 32
+      # Or: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+  - id: session_not_checked_in_api
+    severity: warning
+    description: "API routes outside the middleware matcher that return sensitive data without calling getServerSession(). The middleware only protects matched paths — any API route not in the matcher must check the session itself."
+    bad_example: |
+      // ❌ No session check — any request (including unauthenticated) gets the data
+      export async function GET() {
+        const users = await db.user.findMany({ select: { email: true, salary: true } });
+        return Response.json(users);
+      }
+    good_example: |
+      // ✓ Explicit session check before accessing protected data
+      import { getServerSession } from 'next-auth';
+      import { authOptions } from '@/lib/auth';
+      export async function GET() {
+        const session = await getServerSession(authOptions);
+        if (!session) return new Response('Unauthorized', { status: 401 });
+        const users = await db.user.findMany({ select: { email: true } });
+        return Response.json(users);
+      }
+  - id: duplicated_auth_options
+    severity: warning
+    description: "Defining authOptions inline in multiple API routes instead of importing from src/lib/auth.ts. Each definition can have a different secret or provider config — tokens signed by one definition are rejected by another, causing intermittent auth failures that are hard to debug."
+    bad_example: |
+      // ❌ authOptions defined inline in the route file
+      // app/api/auth/[...nextauth]/route.ts
+      const handler = NextAuth({
+        providers: [GithubProvider({ clientId: '...', clientSecret: '...' })],
+        secret: process.env.NEXTAUTH_SECRET,
+        // Different callbacks or session strategy in another file → token mismatch
+      });
+    good_example: |
+      // ✓ Import from the single source of truth
+      import { authOptions } from '@/lib/auth';
+      const handler = NextAuth(authOptions);
+      export { handler as GET, handler as POST };
+  - id: custom_fields_not_in_callbacks
+    severity: warning
+    description: "Extending the Session type with custom fields (user.id, user.role) but not adding both a jwt callback and a session callback to populate them. The TypeScript types compile, but the fields are undefined at runtime because the values are never written into the token or session object."
+    bad_example: |
+      // next-auth.d.ts: Session.user.role declared as string
+      // authOptions — callbacks are missing entirely
+      export const authOptions: NextAuthOptions = {
+        providers: [...],
+        // session.user.role is always undefined at runtime
+      };
+    good_example: |
+      // ✓ Both callbacks required: jwt enriches the token, session maps token → session
+      callbacks: {
+        async jwt({ token, user }) {
+          if (user) token.role = (user as any).role; // runs on sign-in only
+          return token;
+        },
+        async session({ session, token }) {
+          if (session.user) session.user.role = token.role as string; // every request
+          return session;
+        },
+      },
+  - id: credentials_provider_plain_text
+    severity: critical
+    description: "Using CredentialsProvider and comparing passwords as plain text. If the database is breached, every user's password is immediately exposed. Passwords must always be stored as bcrypt or argon2 hashes."
+    bad_example: |
+      // ❌ Plain text comparison — catastrophic on any database breach
+      CredentialsProvider({
+        authorize: async (credentials) => {
+          const user = await db.user.findFirst({ where: { email: credentials?.email } });
+          if (user?.password === credentials?.password) return user; // raw string compare
+          return null;
+        },
+      })
+    good_example: |
+      // ✓ bcrypt — one-way hash, breach-safe
+      import bcrypt from 'bcryptjs';
+      CredentialsProvider({
+        authorize: async (credentials) => {
+          const user = await db.user.findFirst({ where: { email: credentials?.email } });
+          if (!user?.passwordHash) return null;
+          const valid = await bcrypt.compare(credentials?.password ?? '', user.passwordHash);
+          return valid ? { id: user.id, email: user.email } : null;
+        },
+      })
+  - id: adapter_with_jwt_strategy
+    severity: warning
+    description: "Configuring a database adapter (e.g., PrismaAdapter) with session: { strategy: 'jwt' }. With JWT strategy, NextAuth does not write sessions to the database — the adapter is wired but ignored for session storage, causing confusion and wasted DB connections."
+    bad_example: |
+      // ❌ Adapter installed but JWT strategy means sessions never hit the DB
+      export const authOptions: NextAuthOptions = {
+        adapter: PrismaAdapter(prisma),
+        session: { strategy: 'jwt' }, // adapter's Session table is never written
+      };
+    good_example: |
+      // ✓ Use database strategy when you have an adapter
+      adapter: PrismaAdapter(prisma),
+      session: { strategy: 'database' },
+      // — OR — remove the adapter entirely for JWT-only sessions (no DB table needed)

package/skills/patterns/playwright-e2e.skill.yaml

@@ -0,0 +1,265 @@
+schema_version: "2.0.0"
+id: playwright-e2e
+name: "Playwright E2E"
+version: "2.0.0"
+description: "End-to-end testing with Playwright — Page Object Models, storageState-based auth fixtures, semantic selectors, baseURL from config, globalSetup for one-time login, and CI-optimized retries."
+category: pattern
+language: javascript
+frameworks:
+  - playwright
+dependencies:
+  none:
+    - "@jest/globals"
+detection:
+  dependencies:
+    any:
+      - "@playwright/test"
+  source_indicators:
+    - "from '@playwright/test'"
+    - "test.describe("
+    - "page.goto("
+    - "expect(page)"
+    - "storageState"
+structure:
+  required_dirs:
+    - path: tests/e2e
+      purpose: "E2E test specs organized by user flow or feature. Each spec file covers one major feature (e.g., auth.spec.ts, checkout.spec.ts). Test specs import Page Objects and fixtures — they never contain raw selectors or setup logic."
+  recommended_dirs:
+    - path: tests/e2e/pages
+      purpose: "Page Object Model classes — one class per page or major UI component. The POM encapsulates all selectors and user-facing actions. Test specs call POM methods (loginPage.login(), checkoutPage.placeOrder()) — they never call page.locator() or page.getByRole() directly."
+    - path: tests/e2e/fixtures
+      purpose: "Custom Playwright fixtures extending the base `test` — authenticated page fixtures that load storageState from globalSetup. Import this extended `test` in all specs that need auth instead of the default @playwright/test export."
+    - path: tests/e2e/global-setup
+      purpose: "globalSetup.ts — one-time setup that runs before all specs. Performs the login flow once, saves storageState to a file (e.g., .auth/user.json), and reuses it across all tests via fixtures. Eliminates repeated login in every spec file."
+separation:
+  rules:
+    - concern: page_object_models
+      belongs_in: tests/e2e/pages
+      rule_text: "Encapsulate all page selectors and user-action sequences in Page Object Model classes. Each POM class receives a Playwright Page object in its constructor. Methods represent user intentions (login(), submitForm(), navigateToSettings()) — not individual click/fill operations. Tests call POM methods and assert on outcomes."
+      example: |
+        // tests/e2e/pages/login.page.ts
+        import type { Page } from '@playwright/test';
+
+        export class LoginPage {
+          constructor(private readonly page: Page) {}
+
+          async goto() {
+            await this.page.goto('/login');
+          }
+
+          async login(email: string, password: string) {
+            await this.page.getByLabel('Email').fill(email);
+            await this.page.getByLabel('Password').fill(password);
+            await this.page.getByRole('button', { name: 'Sign in' }).click();
+            // Wait for navigation to complete
+            await this.page.waitForURL('**/dashboard');
+          }
+
+          async getErrorMessage() {
+            return this.page.getByRole('alert').textContent();
+          }
+        }
+
+        // tests/e2e/auth.spec.ts — test calls POM, not selectors
+        const loginPage = new LoginPage(page);
+        await loginPage.goto();
+        await loginPage.login('user@test.com', 'password');
+        await expect(page).toHaveURL('/dashboard');
+      indicators:
+        - "class LoginPage"
+        - "class DashboardPage"
+        - "new LoginPage(page)"
+    - concern: shared_fixtures
+      belongs_in: tests/e2e/fixtures
+      rule_text: "Create custom Playwright fixtures that extend the base test with authenticated page contexts. Load storageState (saved by globalSetup) into the browser context — this skips the login UI entirely for specs that need auth. All authenticated specs import the custom test, not the default one from @playwright/test."
+      example: |
+        // tests/e2e/fixtures/auth.fixture.ts
+        import { test as base, type Page } from '@playwright/test';
+        import path from 'path';
+
+        type AuthFixtures = { authedPage: Page };
+
+        export const test = base.extend<AuthFixtures>({
+          authedPage: async ({ browser }, use) => {
+            const context = await browser.newContext({
+              storageState: path.resolve('.auth/user.json'), // saved by globalSetup
+            });
+            const page = await context.newPage();
+            await use(page);
+            await context.close();
+          },
+        });
+
+        export { expect } from '@playwright/test';
+
+        // tests/e2e/dashboard.spec.ts — uses auth fixture
+        import { test, expect } from '../fixtures/auth.fixture';
+        test('shows user data', async ({ authedPage }) => {
+          await authedPage.goto('/dashboard');
+          await expect(authedPage.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+        });
+      indicators:
+        - "base.extend"
+        - "storageState"
+        - "authedPage"
+    - concern: selectors
+      belongs_in: tests/e2e/pages
+      rule_text: "Use semantic, user-facing selectors in this priority order: (1) getByRole with name — most resilient, matches what screen readers see; (2) getByLabel — for form inputs; (3) getByTestId — for complex interactive components where role/label is impractical; (4) getByText — for links and non-interactive text. Never use CSS class selectors or XPath."
+      example: |
+        // ✓ Role-based — matches semantic HTML, resilient to style changes
+        await page.getByRole('button', { name: 'Submit' }).click();
+        await page.getByRole('link', { name: 'View profile' }).click();
+
+        // ✓ Label-based — for form inputs
+        await page.getByLabel('Email address').fill('user@test.com');
+
+        // ✓ data-testid — for complex interactive widgets without clear role
+        await page.getByTestId('date-picker-input').click();
+
+        // ❌ CSS class — breaks on class rename
+        // await page.locator('.btn-primary').click();
+        // ❌ XPath — brittle to DOM structure changes
+        // await page.locator('//div[@class="form"]/button[1]').click();
+      indicators:
+        - "getByRole"
+        - "getByLabel"
+        - "getByTestId"
+    - concern: config
+      belongs_in: playwright.config.ts
+      rule_text: "Configure baseURL, retries, timeout, and reporter in playwright.config.ts. Never hardcode localhost URLs in test files — use page.goto('/path') which Playwright prepends with baseURL. Use environment variables for baseURL to support testing in different environments (local, staging, CI)."
+      example: |
+        // playwright.config.ts
+        import { defineConfig, devices } from '@playwright/test';
+
+        export default defineConfig({
+          testDir: './tests/e2e',
+          globalSetup: './tests/e2e/global-setup/auth.setup.ts',
+          fullyParallel: true,
+          forbidOnly: !!process.env.CI,
+          retries: process.env.CI ? 2 : 0,
+          reporter: process.env.CI ? 'github' : 'list',
+          use: {
+            baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+            trace: 'on-first-retry', // captures trace on flaky tests in CI
+            screenshot: 'only-on-failure',
+          },
+          projects: [
+            { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+          ],
+        });
+      indicators:
+        - "playwright.config.ts"
+        - "baseURL"
+        - "retries"
+patterns:
+  data_flow:
+    direction: "globalSetup (login once) → storageState file → authedPage fixture → Test spec → POM methods → Browser → Application"
+    rules:
+      - "globalSetup logs in once and saves cookies/localStorage to .auth/user.json."
+      - "Auth fixture loads .auth/user.json — test specs get authenticated page with no login overhead."
+      - "Test specs call POM methods — never raw Playwright selectors."
+      - "baseURL in playwright.config.ts — page.goto('/path') works in all environments."
+      - "Retries and trace collection in CI — flaky tests get 2 retries before failing."
+  error_handling:
+    recommended: "Use trace: 'on-first-retry' to capture full browser trace on flaky tests. Use screenshot: 'only-on-failure' to get a visual snapshot when a test fails in CI."
+  naming:
+    specs: "tests/e2e/[feature].spec.ts"
+    page_objects: "tests/e2e/pages/[page].page.ts"
+    fixtures: "tests/e2e/fixtures/auth.fixture.ts"
+    global_setup: "tests/e2e/global-setup/auth.setup.ts"
+    storage_state: ".auth/user.json"
+anti_patterns:
+  - id: raw_selectors_in_tests
+    severity: warning
+    description: "Using CSS selectors or XPath directly in test spec files instead of Page Object Model methods. When the UI changes (class rename, DOM restructure), every test that uses that selector breaks — with POMs, only one file needs updating."
+    bad_example: |
+      // ❌ Raw selectors in test spec — brittle, hard to maintain
+      test('user can log in', async ({ page }) => {
+        await page.goto('/login');
+        await page.locator('.login-form input[type="email"]').fill('user@test.com');
+        await page.locator('#submit-btn').click();
+        await expect(page.locator('.dashboard-header')).toBeVisible();
+      });
+    good_example: |
+      // ✓ POM method — one place to update when UI changes
+      test('user can log in', async ({ page }) => {
+        const loginPage = new LoginPage(page);
+        await loginPage.goto();
+        await loginPage.login('user@test.com', 'password');
+        await expect(page).toHaveURL('/dashboard');
+      });
+  - id: auth_in_every_test
+    severity: warning
+    description: "Performing the full login flow (goto /login, fill email, fill password, click submit) at the start of every authenticated test. A full login takes 1-3 seconds per test — 100 authenticated tests = 100-300 extra seconds. Use globalSetup + storageState to log in once."
+    bad_example: |
+      // ❌ Full login flow in every test — multiplies test execution time
+      test('view dashboard', async ({ page }) => {
+        await page.goto('/login');
+        await page.fill('#email', 'user@test.com');
+        await page.fill('#password', 'Password123');
+        await page.click('[type="submit"]');
+        await page.waitForURL('/dashboard');
+        // Now the actual test starts...
+      });
+    good_example: |
+      // ✓ Auth fixture provides pre-authenticated page — login ran once in globalSetup
+      test('view dashboard', async ({ authedPage }) => {
+        await authedPage.goto('/dashboard');
+        await expect(authedPage.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+      });
+  - id: no_retries_in_ci
+    severity: warning
+    description: "Running Playwright in CI without retries — a single transient network condition, animation timing issue, or server cold start causes the entire suite to fail. Tests that pass locally may fail in CI due to slower execution."
+    bad_example: |
+      // playwright.config.ts — no CI configuration
+      export default defineConfig({
+        use: { baseURL: 'http://localhost:3000' },
+        // No retries, no CI reporter, no trace collection
+      });
+    good_example: |
+      export default defineConfig({
+        retries: process.env.CI ? 2 : 0,
+        reporter: process.env.CI ? 'github' : 'list',
+        use: {
+          baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+          trace: 'on-first-retry',
+          screenshot: 'only-on-failure',
+        },
+      });
+  - id: hardcoded_base_url_in_goto
+    severity: warning
+    description: "Using hardcoded localhost URLs in page.goto() calls instead of relative paths. Hardcoded URLs break when running tests against staging, CI, or any non-localhost environment. Configure baseURL once in playwright.config.ts."
+    bad_example: |
+      // ❌ Hardcoded URL — only works on localhost:3000
+      await page.goto('http://localhost:3000/dashboard');
+      await page.goto('http://localhost:3000/login');
+    good_example: |
+      // ✓ Relative path — Playwright prepends baseURL from playwright.config.ts
+      await page.goto('/dashboard');
+      await page.goto('/login');
+      // baseURL is configured per-environment: local=localhost:3000, CI=$BASE_URL
+  - id: missing_global_setup
+    severity: warning
+    description: "Re-logging in across every spec file instead of using globalSetup to create a storageState file once. For a test suite with 50 specs all needing authentication, this means 50 complete login flows instead of 1."
+    bad_example: |
+      // ❌ Each spec file logs in separately — N login flows for N specs
+      // auth.spec.ts: logs in at the top
+      // dashboard.spec.ts: logs in again
+      // settings.spec.ts: logs in again
+      // 50 spec files × 2 seconds login = 100 seconds wasted on login
+    good_example: |
+      // ✓ globalSetup logs in once, saves cookies to .auth/user.json
+      // tests/e2e/global-setup/auth.setup.ts
+      async function globalSetup() {
+        const { chromium } = require('@playwright/test');
+        const browser = await chromium.launch();
+        const page = await browser.newPage();
+        await page.goto('/login');
+        await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
+        await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
+        await page.getByRole('button', { name: 'Sign in' }).click();
+        await page.waitForURL('**/dashboard');
+        await page.context().storageState({ path: '.auth/user.json' });
+        await browser.close();
+      }
+      export default globalSetup;