@levironexe/architect 0.1.0

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

@@ -0,0 +1,276 @@
+schema_version: "2.0.0"
+id: selenium-e2e
+name: "Selenium E2E"
+version: "2.0.0"
+description: "End-to-end testing with Selenium WebDriver — Page Object Models with BasePage, explicit waits (no sleeps), driver factory, screenshot capture on failure, data-testid selectors, and driver.quit() in afterEach."
+category: pattern
+language: javascript
+frameworks:
+  - selenium-webdriver
+dependencies:
+  none: []
+detection:
+  dependencies:
+    any:
+      - selenium-webdriver
+      - "@selenium-devtools/expect-webdriver"
+  source_indicators:
+    - "from 'selenium-webdriver'"
+    - "new Builder()"
+    - "driver.findElement("
+    - "By.css("
+    - "until.elementLocated"
+structure:
+  required_dirs:
+    - path: tests/e2e
+      purpose: "E2E test specs organized by user flow or feature. Each spec file tests one major user journey. Specs import Page Objects from tests/e2e/pages/ and the driver factory from tests/e2e/fixtures/ — they never contain raw driver.findElement() calls or By selectors."
+  recommended_dirs:
+    - path: tests/e2e/pages
+      purpose: "Page Object Model classes — one class per page, extending BasePage. BasePage provides shared explicit wait helpers so individual POMs don't copy-paste wait logic. Example: LoginPage extends BasePage, uses this.waitAndFind('login-form') from BasePage."
+    - path: tests/e2e/fixtures
+      purpose: "Driver factory (createDriver.ts) and shared setup helpers. createDriver() is the only place new Builder() is called — tests import and call createDriver() rather than building the WebDriver themselves."
+separation:
+  rules:
+    - concern: page_object_models
+      belongs_in: tests/e2e/pages
+      rule_text: "All locators and user-action sequences go in Page Object Model classes. POM classes extend BasePage which provides shared explicit wait helpers. Tests call high-level POM methods (login(), submitContactForm()) — they never call driver.findElement() or By directly."
+      example: |
+        // tests/e2e/pages/base.page.ts
+        import { WebDriver, By, until, WebElement } from 'selenium-webdriver';
+
+        export class BasePage {
+          constructor(protected driver: WebDriver) {}
+
+          protected async waitAndFind(testId: string, timeout = 5000): Promise<WebElement> {
+            const locator = By.css(`[data-testid="${testId}"]`);
+            await this.driver.wait(until.elementLocated(locator), timeout);
+            return this.driver.findElement(locator);
+          }
+
+          protected async waitForUrl(urlFragment: string, timeout = 5000) {
+            await this.driver.wait(
+              async () => (await this.driver.getCurrentUrl()).includes(urlFragment),
+              timeout,
+              `URL did not contain "${urlFragment}" within ${timeout}ms`
+            );
+          }
+        }
+
+        // tests/e2e/pages/login.page.ts
+        import { By } from 'selenium-webdriver';
+        import { BasePage } from './base.page';
+
+        export class LoginPage extends BasePage {
+          async goto() {
+            await this.driver.get(`${process.env.BASE_URL ?? 'http://localhost:3000'}/login`);
+          }
+
+          async login(email: string, password: string) {
+            const emailInput = await this.waitAndFind('email-input');
+            const passwordInput = await this.waitAndFind('password-input');
+            await emailInput.sendKeys(email);
+            await passwordInput.sendKeys(password);
+            const submitBtn = await this.waitAndFind('login-submit');
+            await submitBtn.click();
+            await this.waitForUrl('/dashboard');
+          }
+
+          async getErrorMessage() {
+            const alert = await this.waitAndFind('error-alert');
+            return alert.getText();
+          }
+        }
+      indicators:
+        - "class LoginPage"
+        - "extends BasePage"
+        - "new LoginPage(driver)"
+    - concern: explicit_waits
+      belongs_in: tests/e2e/pages
+      rule_text: "Always use explicit waits (driver.wait with until.*) for every element interaction. Never use driver.sleep() or setTimeout() — they add fixed delay even when the element is ready, making tests slow and still flaky. Set a consistent timeout (5-10s for most elements, longer for page transitions)."
+      example: |
+        import { until, By, WebDriver } from 'selenium-webdriver';
+
+        // ✓ Explicit wait — resolves immediately when element appears, fails after timeout
+        const locator = By.css('[data-testid="result-list"]');
+        await driver.wait(until.elementLocated(locator), 8000, 'Result list not found within 8s');
+        const el = await driver.findElement(locator);
+        await driver.wait(until.elementIsVisible(el), 3000);
+
+        // ✓ Wait for element to become clickable
+        await driver.wait(until.elementIsEnabled(el), 3000);
+        await el.click();
+
+        // ❌ Fixed sleep — arbitrary, slow, still flaky:
+        // await driver.sleep(3000);
+        // await driver.findElement(locator); // may still fail if 3s wasn't enough
+      indicators:
+        - "driver.wait("
+        - "until.elementLocated"
+        - "until.elementIsVisible"
+    - concern: driver_factory
+      belongs_in: tests/e2e/fixtures
+      rule_text: "Create and configure the WebDriver instance in a single factory function exported from tests/e2e/fixtures/create-driver.ts. Test files import createDriver() — they never call `new Builder()`. This centralizes browser configuration (headless mode in CI, device emulation, etc.) in one place."
+      example: |
+        // tests/e2e/fixtures/create-driver.ts
+        import { Builder, WebDriver, Capabilities } from 'selenium-webdriver';
+        import chrome from 'selenium-webdriver/chrome';
+
+        export async function createDriver(): Promise<WebDriver> {
+          const options = new chrome.Options();
+          if (process.env.CI) {
+            options.addArguments('--headless', '--no-sandbox', '--disable-dev-shm-usage');
+          }
+          return new Builder()
+            .forBrowser('chrome')
+            .setChromeOptions(options)
+            .build();
+        }
+
+        // tests/e2e/auth.spec.ts
+        import { createDriver } from '../fixtures/create-driver';
+        let driver: WebDriver;
+        beforeEach(async () => { driver = await createDriver(); });
+        afterEach(async () => {
+          try { await driver.quit(); } catch { /* already closed */ }
+        });
+      indicators:
+        - "createDriver"
+        - "new Builder()"
+        - "forBrowser("
+    - concern: screenshot_on_failure
+      belongs_in: tests/e2e
+      rule_text: "Capture a screenshot and save it to disk in the afterEach (or afterAll) error handler. In CI, screenshots are the primary debugging tool — without them, a failing test in a headless browser is nearly impossible to diagnose."
+      example: |
+        // tests/e2e/helpers/screenshot.ts
+        import { WebDriver } from 'selenium-webdriver';
+        import fs from 'fs';
+        import path from 'path';
+
+        export async function screenshotOnFailure(driver: WebDriver, testName: string) {
+          const screenshot = await driver.takeScreenshot();
+          const dir = path.resolve('test-screenshots');
+          fs.mkdirSync(dir, { recursive: true });
+          const filename = `${testName.replace(/\s+/g, '-')}-${Date.now()}.png`;
+          fs.writeFileSync(path.join(dir, filename), screenshot, 'base64');
+          console.log(`Screenshot saved: ${path.join(dir, filename)}`);
+        }
+
+        // In test file:
+        afterEach(async function() {
+          // Mocha: this.currentTest.state === 'failed'
+          if (this.currentTest?.state === 'failed') {
+            await screenshotOnFailure(driver, this.currentTest.fullTitle());
+          }
+          await driver.quit();
+        });
+      indicators:
+        - "takeScreenshot"
+        - "writeFileSync"
+        - "test-screenshots"
+patterns:
+  data_flow:
+    direction: "Test → POM Methods (explicit waits) → WebDriver → Browser → Application"
+    rules:
+      - "createDriver() in tests/e2e/fixtures/ is the only place new Builder() is called."
+      - "BasePage provides shared waitAndFind() and waitForUrl() — no copy-pasted wait logic in POMs."
+      - "Tests call POM methods — never raw driver.findElement() or By selectors."
+      - "driver.quit() runs in afterEach/finally — no orphaned browser processes."
+      - "Screenshots are saved on test failure for CI debugging."
+  error_handling:
+    recommended: "Wrap driver.quit() in try/catch in afterEach — if quit fails (already closed), the test runner still continues. Never let a failed driver.quit() block reporting of the actual test failure."
+  naming:
+    specs: "tests/e2e/[feature].spec.ts"
+    base_page: "tests/e2e/pages/base.page.ts — BasePage class with shared wait helpers"
+    page_objects: "tests/e2e/pages/[page].page.ts — extends BasePage"
+    factory: "tests/e2e/fixtures/create-driver.ts — createDriver() function"
+    screenshots: "test-screenshots/[test-name]-[timestamp].png"
+anti_patterns:
+  - id: raw_selectors_in_tests
+    severity: warning
+    description: "Using driver.findElement() and By selectors directly in test spec files instead of Page Object Model methods. When a selector changes, every test that uses it breaks — with POMs, only one file needs updating."
+    bad_example: |
+      // ❌ Raw locators in test file — breaks when selector changes
+      it('can log in', async () => {
+        await driver.findElement(By.css('#email-field')).sendKeys('user@test.com');
+        await driver.findElement(By.css('#password-field')).sendKeys('password');
+        await driver.findElement(By.css('[type="submit"]')).click();
+      });
+    good_example: |
+      // ✓ POM method — one place to update when UI changes
+      it('can log in', async () => {
+        await loginPage.login('user@test.com', 'password');
+      });
+  - id: implicit_or_fixed_waits
+    severity: critical
+    description: "Using driver.manage().setImplicitWaitTimeout() or driver.sleep() instead of explicit waits. Implicit waits apply globally and interact badly with explicit waits. Fixed sleeps are arbitrary — too short causes flakiness, too long slows CI."
+    bad_example: |
+      // ❌ Global implicit wait — interacts badly with explicit waits
+      await driver.manage().setImplicitWaitTimeout(5000);
+
+      // ❌ Fixed sleep — arbitrary, slow on fast machines, still flaky on slow ones
+      await driver.sleep(3000);
+      const el = await driver.findElement(By.css('#result'));
+    good_example: |
+      // ✓ Explicit wait — resolves as soon as element appears, up to 5s
+      const el = await driver.wait(
+        until.elementLocated(By.css('[data-testid="result"]')),
+        5000,
+        'Result element not found within 5s'
+      );
+  - id: driver_not_quit
+    severity: critical
+    description: "Not calling driver.quit() after each test leaves orphaned Chrome/Firefox processes. Each test creates a new browser process — 20 tests without cleanup = 20 browser processes competing for memory. In CI, this causes OOM kills."
+    bad_example: |
+      // ❌ No cleanup — browser process leaked after every test
+      afterEach(async () => {
+        // Missing: await driver.quit();
+      });
+    good_example: |
+      // ✓ quit() in try/catch so cleanup always runs
+      afterEach(async () => {
+        try {
+          await driver.quit();
+        } catch {
+          // driver may already be closed if test crashed it
+        }
+      });
+  - id: new_builder_in_tests
+    severity: warning
+    description: "Calling `new Builder()` in individual test files instead of importing from the shared driver factory. Browser configuration (headless mode, window size, proxy) is duplicated and must be updated in every test file when it changes."
+    bad_example: |
+      // ❌ Builder configuration duplicated in every test file
+      beforeEach(async () => {
+        driver = await new Builder().forBrowser('chrome').build(); // headless? window size? proxy?
+      });
+    good_example: |
+      // ✓ Import from shared factory — one place to configure all browser options
+      import { createDriver } from '../fixtures/create-driver';
+      beforeEach(async () => { driver = await createDriver(); });
+  - id: xpath_selectors
+    severity: warning
+    description: "Using XPath selectors (By.xpath()) for element selection. XPath selectors are tightly coupled to the DOM tree structure — adding a wrapper <div>, moving elements, or renaming tags breaks the selector. They are also slow compared to CSS selectors."
+    bad_example: |
+      // ❌ XPath — breaks on any DOM structure change
+      await driver.findElement(By.xpath('//div[@class="login-form"]/form/div[2]/input')).sendKeys(email);
+      await driver.findElement(By.xpath('//button[contains(text(),"Submit")]')).click();
+    good_example: |
+      // ✓ data-testid selector — stable regardless of DOM structure
+      await driver.findElement(By.css('[data-testid="email-input"]')).sendKeys(email);
+      await driver.findElement(By.css('[data-testid="login-submit"]')).click();
+  - id: no_screenshot_on_failure
+    severity: warning
+    description: "Not capturing screenshots on test failure. A headless browser test that fails in CI with no screenshot leaves only an error message — developers cannot see what the page looked like when the test failed, making debugging extremely difficult."
+    bad_example: |
+      // ❌ No screenshot — only error message on failure
+      afterEach(async () => {
+        await driver.quit(); // no screenshot before quitting
+      });
+    good_example: |
+      // ✓ Screenshot saved before quit when test fails
+      afterEach(async function() {
+        if (this.currentTest?.state === 'failed') {
+          const screenshot = await driver.takeScreenshot();
+          fs.writeFileSync(`test-screenshots/${Date.now()}.png`, screenshot, 'base64');
+        }
+        await driver.quit();
+      });

package/skills/patterns/supabase-auth.skill.yaml

@@ -0,0 +1,298 @@
+schema_version: "2.0.0"
+id: supabase-auth
+name: "Supabase Auth"
+version: "2.0.0"
+description: "Supabase built-in authentication with SSR session management via @supabase/ssr, RLS row-level security policies tied to auth.uid(), OAuth callback routes, and middleware session refresh."
+category: pattern
+language: javascript
+frameworks:
+  - supabase
+dependencies:
+  none:
+    - "@clerk/nextjs"
+    - next-auth
+    - lucia
+detection:
+  dependencies:
+    any:
+      - "@supabase/ssr"
+      - "@supabase/supabase-js"
+  source_indicators:
+    - "supabase.auth.signIn"
+    - "supabase.auth.signUp"
+    - "auth.uid()"
+    - "exchangeCodeForSession"
+    - "createServerClient"
+    - "supabase.auth.getUser"
+structure:
+  required_dirs:
+    - path: app/auth
+      purpose: "Supabase auth UI routes and OAuth callback handler. The callback route at app/auth/callback/route.ts is mandatory for all OAuth providers — it exchanges the one-time code from Supabase's redirect URL for a session cookie. Without it, OAuth sign-in always fails."
+  recommended_dirs:
+    - path: src/lib
+      purpose: "Supabase client factory functions — one file for server contexts (createClient reading from Next.js cookies) and one for browser contexts (createBrowserClient). These files are imported by Server Components, API routes, middleware, and Client Components respectively. Never mix them."
+    - path: middleware.ts
+      purpose: "Session refresh middleware — calls supabase.auth.getUser() on every request to refresh the session cookie before it expires. Without this, users are silently logged out when their session cookie ages past the expiry window even if they are actively using the app."
+separation:
+  rules:
+    - concern: ssr_sessions
+      belongs_in: src/lib
+      rule_text: "Use @supabase/ssr (not @supabase/supabase-js directly) for Next.js and server-rendered apps. Create a server client in src/lib/supabase-server.ts that reads and writes session cookies using Next.js cookie utilities. Create a browser client in src/lib/supabase-browser.ts for Client Components."
+      example: |
+        // src/lib/supabase-server.ts — for Server Components, API routes, middleware
+        import { createServerClient } from '@supabase/ssr';
+        import { cookies } from 'next/headers';
+
+        export async function createClient() {
+          const cookieStore = await cookies();
+          return createServerClient(
+            process.env.NEXT_PUBLIC_SUPABASE_URL!,
+            process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+            {
+              cookies: {
+                getAll: () => cookieStore.getAll(),
+                setAll: (cookiesToSet) => {
+                  cookiesToSet.forEach(({ name, value, options }) =>
+                    cookieStore.set(name, value, options)
+                  );
+                },
+              },
+            }
+          );
+        }
+
+        // src/lib/supabase-browser.ts — for Client Components only
+        import { createBrowserClient } from '@supabase/ssr';
+        export const supabase = createBrowserClient(
+          process.env.NEXT_PUBLIC_SUPABASE_URL!,
+          process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+        );
+      indicators:
+        - "createServerClient"
+        - "@supabase/ssr"
+        - "createBrowserClient"
+        - "exchangeCodeForSession"
+    - concern: middleware_refresh
+      belongs_in: middleware.ts
+      rule_text: "Call supabase.auth.getUser() in middleware on every request to refresh the session cookie. This keeps short-lived access tokens alive as long as the user is active. Without middleware refresh, sessions expire mid-visit even when the user is actively interacting with the app."
+      example: |
+        // middleware.ts
+        import { createServerClient } from '@supabase/ssr';
+        import { NextResponse, type NextRequest } from 'next/server';
+
+        export async function middleware(request: NextRequest) {
+          let supabaseResponse = NextResponse.next({ request });
+
+          const supabase = createServerClient(
+            process.env.NEXT_PUBLIC_SUPABASE_URL!,
+            process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+            {
+              cookies: {
+                getAll: () => request.cookies.getAll(),
+                setAll: (cookiesToSet) => {
+                  cookiesToSet.forEach(({ name, value, options }) => {
+                    request.cookies.set(name, value);
+                    supabaseResponse.cookies.set(name, value, options);
+                  });
+                },
+              },
+            }
+          );
+
+          // Refreshes the session if expired — MUST NOT be removed
+          const { data: { user } } = await supabase.auth.getUser();
+
+          if (!user && !request.nextUrl.pathname.startsWith('/login')) {
+            const url = request.nextUrl.clone();
+            url.pathname = '/login';
+            return NextResponse.redirect(url);
+          }
+
+          return supabaseResponse;
+        }
+      indicators:
+        - "supabase.auth.getUser()"
+        - "createServerClient"
+        - "supabaseResponse"
+    - concern: rls_integration
+      belongs_in: src/lib
+      rule_text: "Every table that stores user data must have Row Level Security enabled and at least one policy using auth.uid(). Supabase Auth's primary security mechanism is RLS — authenticated queries still see all rows if no policy restricts them. Write policies before writing application code."
+      example: |
+        -- Enable RLS on every user-data table (run in Supabase SQL editor)
+        ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+        ALTER TABLE comments ENABLE ROW LEVEL SECURITY;
+        ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
+
+        -- Policy: users can only read, create, update, and delete their own rows
+        CREATE POLICY "own posts" ON posts
+          FOR ALL
+          USING (auth.uid() = user_id)
+          WITH CHECK (auth.uid() = user_id);
+
+        -- Policy: profiles are readable by everyone but only editable by owner
+        CREATE POLICY "public profiles read" ON profiles
+          FOR SELECT USING (true);
+        CREATE POLICY "own profile write" ON profiles
+          FOR ALL USING (auth.uid() = id);
+      indicators:
+        - "auth.uid()"
+        - "USING ("
+        - "CREATE POLICY"
+        - "ROW LEVEL SECURITY"
+    - concern: social_providers
+      belongs_in: app/auth
+      rule_text: "Configure OAuth providers in the Supabase dashboard (Authentication > Providers) — not in code. Create a mandatory callback route at app/auth/callback/route.ts that calls supabase.auth.exchangeCodeForSession() to convert the one-time OAuth code into a session cookie."
+      example: |
+        // app/auth/callback/route.ts — mandatory for all OAuth providers
+        import { createServerClient } from '@supabase/ssr';
+        import { cookies } from 'next/headers';
+        import { NextResponse } from 'next/server';
+
+        export async function GET(request: Request) {
+          const { searchParams, origin } = new URL(request.url);
+          const code = searchParams.get('code');
+          const next = searchParams.get('next') ?? '/';
+
+          if (code) {
+            const cookieStore = await cookies();
+            const supabase = createServerClient(
+              process.env.NEXT_PUBLIC_SUPABASE_URL!,
+              process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+              { cookies: { getAll: () => cookieStore.getAll(), setAll: (cs) => cs.forEach(({ name, value, options }) => cookieStore.set(name, value, options)) } }
+            );
+            const { error } = await supabase.auth.exchangeCodeForSession(code);
+            if (!error) {
+              return NextResponse.redirect(`${origin}${next}`);
+            }
+          }
+
+          return NextResponse.redirect(`${origin}/auth/auth-code-error`);
+        }
+      indicators:
+        - "exchangeCodeForSession"
+        - "app/auth/callback"
+        - "searchParams.get('code')"
+    - concern: server_component_auth
+      belongs_in: app
+      rule_text: "In Server Components, call supabase.auth.getUser() (not getSession()) to get the authenticated user. getUser() validates the token with Supabase's server — getSession() only reads the local cookie which can be forged. Always use getUser() for security-sensitive decisions."
+      example: |
+        // app/dashboard/page.tsx — Server Component with auth check
+        import { createClient } from '@/lib/supabase-server';
+        import { redirect } from 'next/navigation';
+
+        export default async function DashboardPage() {
+          const supabase = await createClient();
+          // getUser() validates with Supabase server — getSession() does NOT
+          const { data: { user }, error } = await supabase.auth.getUser();
+          if (error || !user) redirect('/login');
+
+          const { data: posts } = await supabase
+            .from('posts')
+            .select('*')
+            .eq('user_id', user.id); // RLS also enforces this at DB level
+
+          return <PostList posts={posts ?? []} />;
+        }
+      indicators:
+        - "supabase.auth.getUser()"
+        - "from('@/lib/supabase-server')"
+patterns:
+  data_flow:
+    direction: "Request → Middleware (session refresh) → Server Component (getUser) → RLS-enforced Supabase Query → Database"
+    rules:
+      - "Middleware refreshes the session cookie on every request — without it users get silently logged out mid-session."
+      - "Server Components call supabase.auth.getUser() for the authenticated user — never getSession() for security decisions."
+      - "Client Components use the browser client from supabase-browser.ts — it reads the session from localStorage."
+      - "RLS policies enforce per-user data isolation at the database level — authenticated queries still need policies to restrict rows."
+      - "The OAuth callback route at app/auth/callback/route.ts is the mandatory landing point for all social provider sign-ins."
+      - "Service role key is only used server-side for admin operations that intentionally bypass RLS — never in browser code."
+  error_handling:
+    recommended: "Always call supabase.auth.getUser() (not getSession()) for auth decisions — getUser() validates with Supabase's server. Check both error and data.user being null. Redirect to /login when no valid session."
+  naming:
+    callback_route: "app/auth/callback/route.ts — OAuth code exchange via exchangeCodeForSession()"
+    server_client: "src/lib/supabase-server.ts — SSR client reading session from cookies (@supabase/ssr)"
+    browser_client: "src/lib/supabase-browser.ts — browser client (createBrowserClient from @supabase/ssr)"
+    rls_policies: "Named 'own [resource]' — e.g. 'own posts', 'own profiles'; reference auth.uid() = user_id"
+anti_patterns:
+  - id: no_rls_with_auth
+    severity: critical
+    description: "Using Supabase Auth to authenticate users but not creating RLS policies. All authenticated users can read and modify each other's data — enabling auth without RLS does not provide any data isolation. This is the most common Supabase security mistake."
+    bad_example: |
+      -- ❌ RLS enabled but no policies — Supabase defaults to DENY for anon,
+      -- but ALL authenticated users can read ALL rows from each other
+      ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+      -- Missing: CREATE POLICY
+      -- Any signed-in user: SELECT * FROM posts → sees every user's posts
+    good_example: |
+      -- ✓ RLS with per-user policy — each user only sees their own rows
+      ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+      CREATE POLICY "own posts" ON posts
+        FOR ALL
+        USING (auth.uid() = user_id)
+        WITH CHECK (auth.uid() = user_id);
+  - id: get_session_for_auth_decisions
+    severity: critical
+    description: "Using supabase.auth.getSession() to verify authentication instead of supabase.auth.getUser(). getSession() reads the local session cookie without validating it with Supabase's server — a forged or replayed cookie will pass getSession() but fail getUser()."
+    bad_example: |
+      // ❌ getSession() only reads the cookie — can be forged
+      const { data: { session } } = await supabase.auth.getSession();
+      if (!session) redirect('/login');
+      // session.user is from the unvalidated cookie — not trustworthy
+      const userId = session.user.id;
+    good_example: |
+      // ✓ getUser() validates with Supabase's auth server — cannot be forged
+      const { data: { user }, error } = await supabase.auth.getUser();
+      if (error || !user) redirect('/login');
+      const userId = user.id; // validated server-side
+  - id: direct_supabase_js_on_server
+    severity: warning
+    description: "Using @supabase/supabase-js createClient() in Server Components instead of @supabase/ssr createServerClient(). The plain createClient() has no way to read Next.js cookie storage — it cannot find the user session and all authenticated queries run as anonymous."
+    bad_example: |
+      // ❌ Plain supabase-js on server — can't read session cookies
+      import { createClient } from '@supabase/supabase-js';
+      const supabase = createClient(URL, ANON_KEY);
+      // supabase.auth.getUser() always returns null — session is invisible
+      const { data: { user } } = await supabase.auth.getUser(); // user = null
+    good_example: |
+      // ✓ SSR client reads session from Next.js cookie store
+      import { createClient } from '@/lib/supabase-server';
+      const supabase = await createClient();
+      const { data: { user } } = await supabase.auth.getUser(); // user = authenticated user
+  - id: missing_callback_route
+    severity: warning
+    description: "Using OAuth social login (GitHub, Google, etc.) without an auth callback route. When Supabase redirects back after OAuth, there is nowhere to exchange the one-time code for a session — the user lands on the redirect URL with a 404 or a broken page."
+    bad_example: |
+      // ❌ No callback route — sign-in with OAuth always fails with a broken redirect
+      await supabase.auth.signInWithOAuth({ provider: 'github' });
+      // Supabase redirects to: /auth/callback?code=... → 404 Not Found
+    good_example: |
+      // ✓ app/auth/callback/route.ts exists and calls exchangeCodeForSession()
+      const { error } = await supabase.auth.exchangeCodeForSession(code);
+      if (!error) return NextResponse.redirect(`${origin}/dashboard`);
+  - id: missing_middleware_refresh
+    severity: warning
+    description: "Not running session refresh in middleware. Supabase access tokens expire after 1 hour by default. Without middleware calling getUser() on each request, the session cookie ages and the user is silently logged out even while actively using the app."
+    bad_example: |
+      // middleware.ts — missing or empty, no session refresh
+      export function middleware(req: NextRequest) {
+        return NextResponse.next(); // session cookie never refreshed
+      }
+      // User gets logged out every hour even while actively using the app
+    good_example: |
+      // ✓ Middleware calls supabase.auth.getUser() which refreshes the access token
+      const supabase = createServerClient(URL, KEY, { cookies: { ... } });
+      await supabase.auth.getUser(); // side effect: refreshes session if near expiry
+  - id: insecure_rls_policy
+    severity: critical
+    description: "Writing an RLS policy with USING (true) which grants full access to all authenticated users — equivalent to having no RLS at all. Often introduced by accident when following generic Supabase examples."
+    bad_example: |
+      -- ❌ USING (true) grants every authenticated user full table access
+      CREATE POLICY "allow all" ON posts
+        FOR ALL USING (true);
+      -- Any logged-in user can read, update, or delete any other user's posts
+    good_example: |
+      -- ✓ Scope the policy to the authenticated user's own rows
+      CREATE POLICY "own posts" ON posts
+        FOR ALL
+        USING (auth.uid() = user_id)
+        WITH CHECK (auth.uid() = user_id);