leopost/.planning/phases/01-foundation-auth/01-01-PLAN.md

---
phase: 01-foundation-auth
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - package.json
  - tsconfig.json
  - next.config.ts
  - tailwind.config.ts
  - postcss.config.mjs
  - .env.local
  - .env.example
  - src/lib/supabase/client.ts
  - src/lib/supabase/server.ts
  - src/app/layout.tsx
  - src/app/page.tsx
  - src/app/globals.css
autonomous: true
user_setup:
  - service: supabase
    why: "Database and authentication backend"
    env_vars:
      - name: NEXT_PUBLIC_SUPABASE_URL
        source: "Supabase Dashboard -> Project Settings -> API -> Project URL"
      - name: NEXT_PUBLIC_SUPABASE_ANON_KEY
        source: "Supabase Dashboard -> Project Settings -> API -> anon public"
      - name: SUPABASE_SERVICE_ROLE_KEY
        source: "Supabase Dashboard -> Project Settings -> API -> service_role (secret)"

must_haves:
  truths:
    - "Next.js dev server starts without errors"
    - "Supabase client connects to project"
    - "Environment variables are loaded correctly"
  artifacts:
    - path: "src/lib/supabase/client.ts"
      provides: "Browser Supabase client for Client Components"
      exports: ["createClient"]
    - path: "src/lib/supabase/server.ts"
      provides: "Server Supabase client for Server Components/Actions"
      exports: ["createClient"]
    - path: ".env.local"
      provides: "Environment configuration"
      contains: "NEXT_PUBLIC_SUPABASE_URL"
  key_links:
    - from: "src/lib/supabase/client.ts"
      to: ".env.local"
      via: "process.env.NEXT_PUBLIC_*"
      pattern: "process\\.env\\.NEXT_PUBLIC_SUPABASE"
    - from: "src/lib/supabase/server.ts"
      to: "next/headers cookies()"
      via: "cookie handling for SSR"
      pattern: "cookies\\(\\)"
---

<objective>
Initialize Next.js 14 project with Supabase client configuration using the official @supabase/ssr package for App Router compatibility.

Purpose: Establish the foundational project structure and Supabase connectivity that all subsequent auth work depends on.

Output: Working Next.js 14 app with properly configured Supabase clients (browser + server) ready for auth implementation.
</objective>

<execution_context>
@C:\Users\miche\.claude/get-shit-done/workflows/execute-plan.md
@C:\Users\miche\.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-foundation-auth/01-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Initialize Next.js 14 project with TypeScript and Tailwind</name>
  <files>
    package.json
    tsconfig.json
    next.config.ts
    tailwind.config.ts
    postcss.config.mjs
    src/app/layout.tsx
    src/app/page.tsx
    src/app/globals.css
  </files>
  <action>
    Create Next.js 14 project with App Router:

    ```bash
    npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm
    ```

    If directory not empty, use --force or clean first.

    After init, install Supabase packages:
    ```bash
    npm install @supabase/supabase-js @supabase/ssr zod react-hook-form
    ```

    Update src/app/page.tsx to a simple placeholder:
    ```tsx
    export default function Home() {
      return (
        <main className="flex min-h-screen flex-col items-center justify-center p-24">
          <h1 className="text-4xl font-bold">Leopost</h1>
          <p className="mt-4 text-gray-600">Setup in corso...</p>
        </main>
      )
    }
    ```

    Ensure next.config.ts uses the new format (not .js):
    ```typescript
    import type { NextConfig } from 'next'

    const nextConfig: NextConfig = {
      // config options here
    }

    export default nextConfig
    ```
  </action>
  <verify>
    Run `npm run dev` - server starts on localhost:3000 without errors.
    Visit http://localhost:3000 - shows Leopost placeholder.
  </verify>
  <done>
    Next.js 14 project initialized with TypeScript, Tailwind, App Router, and Supabase packages installed.
  </done>
</task>

<task type="auto">
  <name>Task 2: Configure environment variables</name>
  <files>
    .env.local
    .env.example
    .gitignore
  </files>
  <action>
    Create .env.example (committed to git, template for others):
    ```
    # Supabase Configuration
    NEXT_PUBLIC_SUPABASE_URL=your-project-url
    NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
    SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

    # App Configuration
    NEXT_PUBLIC_APP_URL=http://localhost:3000
    ```

    Create .env.local with actual Supabase credentials:
    - Get URL from Supabase Dashboard -> Project Settings -> API -> Project URL
    - Get anon key from Supabase Dashboard -> Project Settings -> API -> anon public
    - Get service_role key from Supabase Dashboard -> Project Settings -> API -> service_role

    NOTE: If Supabase project doesn't exist yet, create placeholder values and document that user must create project.

    Verify .gitignore includes:
    ```
    .env*.local
    ```
    (This should already be present from create-next-app)
  </action>
  <verify>
    - .env.example exists and is NOT in .gitignore
    - .env.local exists and IS gitignored
    - Run `git status` - .env.local should NOT appear
  </verify>
  <done>
    Environment files configured with Supabase credentials (or placeholders if project not yet created).
  </done>
</task>

<task type="auto">
  <name>Task 3: Create Supabase client utilities (dual client pattern)</name>
  <files>
    src/lib/supabase/client.ts
    src/lib/supabase/server.ts
  </files>
  <action>
    Create src/lib/supabase/client.ts for Client Components:
    ```typescript
    import { createBrowserClient } from '@supabase/ssr'

    export function createClient() {
      return createBrowserClient(
        process.env.NEXT_PUBLIC_SUPABASE_URL!,
        process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
      )
    }
    ```

    Create src/lib/supabase/server.ts for Server Components, Route Handlers, Server Actions:
    ```typescript
    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() {
              return cookieStore.getAll()
            },
            setAll(cookiesToSet) {
              try {
                cookiesToSet.forEach(({ name, value, options }) =>
                  cookieStore.set(name, value, options)
                )
              } catch {
                // The `setAll` method was called from a Server Component.
                // This can be ignored if you have middleware refreshing user sessions.
              }
            },
          },
        }
      )
    }
    ```

    IMPORTANT:
    - Use @supabase/ssr NOT @supabase/auth-helpers-nextjs (deprecated)
    - Server client uses async cookies() (Next.js 15 requirement)
    - The try/catch in setAll is required for Server Components
  </action>
  <verify>
    - Both files exist with correct exports
    - `npm run build` completes without TypeScript errors
    - No import errors in IDE
  </verify>
  <done>
    Dual Supabase client pattern implemented: client.ts for browser, server.ts for SSR/Server Actions.
  </done>
</task>

</tasks>

<verification>
After all tasks complete:
1. `npm run dev` starts without errors
2. `npm run build` completes successfully
3. Both Supabase client files exist and export createClient
4. Environment variables are configured (even if placeholder)
5. Project structure follows Next.js 14 App Router conventions
</verification>

<success_criteria>
- Next.js 14 development server runs at localhost:3000
- Supabase packages installed: @supabase/supabase-js, @supabase/ssr
- Form packages installed: zod, react-hook-form
- Dual client pattern implemented (client.ts + server.ts)
- Environment configuration ready for Supabase connection
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation-auth/01-01-SUMMARY.md`
</output>