chore: merge executor worktree (worktree-agent-af11b313)

.planning/phases/07-setup-wizard/07-02-SUMMARY.md

@@ -0,0 +1,74 @@
+---
+phase: 07-setup-wizard
+plan: 02
+subsystem: frontend/setup-wizard
+tags: [wizard, completion, routing, first-run-redirect]
+dependency_graph:
+  requires: [src/hooks/useWizardState.ts, src/hooks/useCategories.ts, src/hooks/useTemplate.ts, src/hooks/useFirstRunState.ts, src/data/presets.ts]
+  provides: [src/components/setup/ReviewStep.tsx, /setup route, first-run redirect]
+  affects: [src/pages/SetupPage.tsx, src/App.tsx, src/pages/DashboardPage.tsx]
+tech_stack:
+  added: []
+  patterns: [wizard-completion-flow, category-dedup-on-constraint, query-invalidation-before-redirect]
+key_files:
+  created:
+    - src/components/setup/ReviewStep.tsx
+  modified:
+    - src/pages/SetupPage.tsx
+    - src/App.tsx
+    - src/pages/DashboardPage.tsx
+decisions:
+  - "Moved hook calls above early returns in DashboardPage to comply with React rules of hooks"
+  - "Skip on step 3 calls same handleSkipSetup as global skip (per UI-SPEC)"
+metrics:
+  duration: 145s
+  completed: 2026-04-20T19:10:45Z
+  tasks_completed: 2
+  tasks_total: 2
+  files_created: 1
+  files_modified: 3
+---
+
+# Phase 07 Plan 02: Setup Wizard Completion and Routing Summary
+
+ReviewStep with grouped read-only summary, wizard completion logic (category + template item creation with duplicate handling), skip flow, /setup route registration, and first-run redirect from dashboard.
+
+## Commits
+
+| Task | Commit | Description |
+|------|--------|-------------|
+| 1 | 396d342 | ReviewStep component and wizard completion/skip logic |
+| 2 | 6b75f14 | Register /setup route and add first-run redirect |
+
+## What Was Built
+
+1. **ReviewStep** - Read-only summary component showing income, grouped checked items by category type, total expenses, and remaining balance. Uses Intl.NumberFormat for currency formatting. Remaining is colored green (text-on-budget) when positive, red (text-destructive) when negative.
+
+2. **Wizard Completion Logic** - handleComplete creates one category per needed type (handles 23505 duplicate constraint), creates template items for all checked presets, marks profiles.setup_completed=true, clears localStorage wizard state, invalidates React Query cache, shows toast, and redirects to dashboard.
+
+3. **Skip Flow** - handleSkipSetup clears localStorage, marks setup_completed=true without creating any data, and redirects to dashboard.
+
+4. **Double-submit Prevention** - `completing` state disables all buttons during API calls (T-07-04 mitigation).
+
+5. **/setup Route** - Registered in App.tsx as a protected standalone page (inside ProtectedRoute, outside AppLayout). Unauthenticated users are redirected to /login (T-07-06 mitigation).
+
+6. **First-run Redirect** - DashboardPage uses useFirstRunState to detect users with no categories/template items and redirects them to /setup. Shows DashboardSkeleton during loading.
+
+7. **Redirect Loop Prevention** - Query invalidation for ["categories"] and ["template-items"] after completion ensures useFirstRunState reads fresh data showing isFirstRun=false (T-07-07 mitigation).
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed React hooks rule violation in DashboardPage**
+- **Found during:** Task 2
+- **Issue:** Plan instructed placing early returns before useMonthParam/useBudgets calls, which violates React rules of hooks (hooks cannot be called conditionally)
+- **Fix:** Moved all hook calls (useMonthParam, useBudgets, useMemo) above the early return statements
+- **Files modified:** src/pages/DashboardPage.tsx
+- **Commit:** 6b75f14
+
+## Known Stubs
+
+None - all stubs from Plan 01 have been resolved.
+
+## Self-Check: PASSED

src/App.tsx

@@ -3,6 +3,7 @@ import { useAuth } from "@/hooks/useAuth"
 import AppLayout from "@/components/AppLayout"
 import LoginPage from "@/pages/LoginPage"
 import RegisterPage from "@/pages/RegisterPage"
+import SetupPage from "@/pages/SetupPage"
 import DashboardPage from "@/pages/DashboardPage"
 import CategoriesPage from "@/pages/CategoriesPage"
 import TemplatePage from "@/pages/TemplatePage"
@@ -44,6 +45,14 @@ export default function App() {
           </PublicRoute>
         }
       />
+      <Route
+        path="/setup"
+        element={
+          <ProtectedRoute>
+            <SetupPage />
+          </ProtectedRoute>
+        }
+      />
       <Route
         element={
           <ProtectedRoute>

src/components/setup/ReviewStep.tsx

@@ -0,0 +1,118 @@
+import { useTranslation } from "react-i18next"
+import { PRESETS } from "@/data/presets"
+import type { CategoryType } from "@/lib/types"
+import { Separator } from "@/components/ui/separator"
+import { CategoryGroupHeader } from "./CategoryGroupHeader"
+
+interface ReviewStepProps {
+  income: number
+  selectedItems: Record<string, { checked: boolean; amount: number }>
+  currency: string
+}
+
+const TYPE_ORDER: CategoryType[] = [
+  "income",
+  "bill",
+  "variable_expense",
+  "debt",
+  "saving",
+  "investment",
+]
+
+export function ReviewStep({ income, selectedItems, currency }: ReviewStepProps) {
+  const { t } = useTranslation()
+
+  const fmt = (amount: number) =>
+    new Intl.NumberFormat(undefined, {
+      style: "currency",
+      currency,
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 2,
+    }).format(amount)
+
+  const checkedPresets = PRESETS.filter((p) => selectedItems[p.slug]?.checked)
+
+  // Group checked items by type
+  const grouped = TYPE_ORDER.reduce<
+    Record<CategoryType, typeof checkedPresets>
+  >((acc, type) => {
+    const items = checkedPresets.filter((p) => p.type === type)
+    if (items.length > 0) acc[type] = items
+    return acc
+  }, {} as Record<CategoryType, typeof checkedPresets>)
+
+  const totalExpenses = checkedPresets.reduce(
+    (sum, p) => sum + (selectedItems[p.slug]?.amount ?? 0),
+    0
+  )
+  const remaining = income - totalExpenses
+
+  return (
+    <div className="space-y-2">
+      {/* Income row */}
+      <div className="flex justify-between py-2">
+        <span className="text-sm font-semibold">
+          {t("setup.step3.incomeLabel")}
+        </span>
+        <span className="text-sm font-semibold">{fmt(income)}</span>
+      </div>
+      <Separator />
+
+      {/* Grouped items */}
+      {checkedPresets.length === 0 ? (
+        <p className="text-sm text-muted-foreground py-4">
+          {t("setup.step3.empty")}
+        </p>
+      ) : (
+        <>
+          {TYPE_ORDER.filter((type) => grouped[type]).map((type) => (
+            <div key={type}>
+              <CategoryGroupHeader
+                type={type}
+                label={t(`categories.types.${type}`)}
+                count={grouped[type].length}
+              />
+              {grouped[type].map((item) => (
+                <div
+                  key={item.slug}
+                  className="flex justify-between py-1.5 px-1"
+                >
+                  <span className="text-sm">
+                    {t(`presets.${item.type}.${item.slug}`)}
+                  </span>
+                  <span className="text-sm text-right">
+                    {fmt(selectedItems[item.slug]?.amount ?? 0)}
+                  </span>
+                </div>
+              ))}
+            </div>
+          ))}
+        </>
+      )}
+
+      <Separator />
+
+      {/* Totals */}
+      <div className="space-y-1 pt-2">
+        <div className="flex justify-between">
+          <span className="text-sm font-semibold">
+            {t("setup.step3.totalLabel")}
+          </span>
+          <span className="text-sm font-semibold">{fmt(totalExpenses)}</span>
+        </div>
+        <div className="flex justify-between">
+          <span className="text-base font-semibold">
+            {t("setup.step3.remainingLabel")}
+          </span>
+          <span
+            className={`text-base font-semibold ${
+              remaining >= 0 ? "text-on-budget" : "text-destructive"
+            }`}
+          >
+            {fmt(remaining)}
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}

src/pages/DashboardPage.tsx

@@ -1,5 +1,7 @@
 import { useState, useMemo } from "react"
+import { Navigate } from "react-router-dom"
 import { useTranslation } from "react-i18next"
+import { useFirstRunState } from "@/hooks/useFirstRunState"
 import { useBudgets, useBudgetDetail } from "@/hooks/useBudgets"
 import { useMonthParam } from "@/hooks/useMonthParam"
 import type { CategoryType } from "@/lib/types"
@@ -271,6 +273,7 @@ function DashboardContent({ budgetId }: { budgetId: string }) {
 
 export default function DashboardPage() {
   const { t } = useTranslation()
+  const { isFirstRun, loading: firstRunLoading } = useFirstRunState()
   const { month } = useMonthParam()
   const { budgets, loading, createBudget, generateFromTemplate } = useBudgets()
 
@@ -286,6 +289,9 @@ export default function DashboardPage() {
 
   const [parsedYear, parsedMonth] = month.split("-").map(Number)
 
+  if (firstRunLoading) return <DashboardSkeleton />
+  if (isFirstRun) return <Navigate to="/setup" replace />
+
   return (
     <PageShell
       title={t("dashboard.title")}

src/pages/SetupPage.tsx

@@ -1,12 +1,19 @@
 import { useState } from "react"
 import { useTranslation } from "react-i18next"
+import { useNavigate } from "react-router-dom"
+import { useQueryClient } from "@tanstack/react-query"
+import { toast } from "sonner"
 import { useAuth } from "@/hooks/useAuth"
 import { useWizardState } from "@/hooks/useWizardState"
+import { useCategories } from "@/hooks/useCategories"
+import { useTemplate } from "@/hooks/useTemplate"
 import { supabase } from "@/lib/supabase"
+import { PRESETS } from "@/data/presets"
 import type { Profile } from "@/lib/types"
 import { WizardStepper } from "@/components/setup/WizardStepper"
 import { IncomeStep } from "@/components/setup/IncomeStep"
 import { RecurringItemsStep } from "@/components/setup/RecurringItemsStep"
+import { ReviewStep } from "@/components/setup/ReviewStep"
 import { Button } from "@/components/ui/button"
 import {
   Card,
@@ -20,8 +27,14 @@ import { useEffect } from "react"
 export default function SetupPage() {
   const { t } = useTranslation()
   const { user, loading: authLoading } = useAuth()
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
   const [profile, setProfile] = useState<Profile | null>(null)
   const [profileLoading, setProfileLoading] = useState(true)
+  const [completing, setCompleting] = useState(false)
+
+  const { categories, create } = useCategories()
+  const { createItem } = useTemplate()
 
   useEffect(() => {
     if (!user) return
@@ -38,7 +51,7 @@ export default function SetupPage() {
 
   const userId = user?.id ?? ""
   const currency = profile?.currency ?? "EUR"
-  const { state, setStep, setIncome, toggleItem, setItemAmount } =
+  const { state, setStep, setIncome, toggleItem, setItemAmount, clearState } =
     useWizardState(userId)
 
   const [incomeError, setIncomeError] = useState<string | null>(null)
@@ -89,6 +102,7 @@ export default function SetupPage() {
   function handleSkipStep() {
     if (state.currentStep === 1) setStep(2)
     else if (state.currentStep === 2) setStep(3)
+    else if (state.currentStep === 3) handleSkipSetup()
   }
 
   function handleStepClick(step: 1 | 2 | 3) {
@@ -97,10 +111,98 @@ export default function SetupPage() {
     }
   }
 
+  async function handleComplete() {
+    setCompleting(true)
+    try {
+      const checkedItems = PRESETS.filter(
+        (p) => state.selectedItems[p.slug]?.checked
+      )
+
+      // 1. Determine unique category types needed
+      const typesNeeded = [...new Set(checkedItems.map((i) => i.type))]
+
+      // 2. Create one category per type
+      const categoryMap: Record<string, string> = {}
+      for (const type of typesNeeded) {
+        try {
+          const cat = await create.mutateAsync({
+            name: t(`categories.types.${type}`),
+            type,
+          })
+          categoryMap[type] = cat.id
+        } catch (e: any) {
+          // Unique constraint violation (23505) = category already exists, fetch it
+          if (e?.code === "23505" || e?.message?.includes("duplicate")) {
+            const existing = categories.find((c) => c.type === type)
+            if (existing) categoryMap[type] = existing.id
+          } else {
+            throw e
+          }
+        }
+      }
+
+      // 3. If categories were fetched from cache but not found, refetch
+      if (Object.keys(categoryMap).length < typesNeeded.length) {
+        await queryClient.invalidateQueries({ queryKey: ["categories"] })
+      }
+
+      // 4. Create template items for each checked preset
+      let partialFailure = false
+      for (const item of checkedItems) {
+        try {
+          await createItem.mutateAsync({
+            category_id: categoryMap[item.type],
+            item_tier: item.item_tier,
+            budgeted_amount: state.selectedItems[item.slug].amount,
+          })
+        } catch {
+          partialFailure = true
+        }
+      }
+
+      // 5. Mark setup complete
+      await supabase
+        .from("profiles")
+        .update({ setup_completed: true })
+        .eq("id", user!.id)
+
+      // 6. Clear wizard state
+      clearState()
+
+      // 7. Invalidate queries to prevent redirect loop
+      await queryClient.invalidateQueries({ queryKey: ["categories"] })
+      await queryClient.invalidateQueries({ queryKey: ["template-items"] })
+
+      // 8. Toast and redirect
+      if (partialFailure) {
+        toast.error(t("setup.toast.partialError"))
+      } else {
+        toast.success(t("setup.toast.success"))
+      }
+      navigate("/", { replace: true })
+    } catch {
+      toast.error(t("setup.toast.error"))
+    } finally {
+      setCompleting(false)
+    }
+  }
+
+  async function handleSkipSetup() {
+    clearState()
+    await supabase
+      .from("profiles")
+      .update({ setup_completed: true })
+      .eq("id", user!.id)
+    navigate("/", { replace: true })
+  }
+
   return (
     <div className="flex min-h-screen items-center justify-center bg-background p-4">
       <div className="w-full max-w-2xl">
-        <WizardStepper currentStep={state.currentStep} onStepClick={handleStepClick} />
+        <WizardStepper
+          currentStep={state.currentStep}
+          onStepClick={handleStepClick}
+        />
 
         <Card className="w-full border border-border shadow-sm">
           <CardHeader className="pb-2">
@@ -132,35 +234,42 @@ export default function SetupPage() {
             )}
 
             {state.currentStep === 3 && (
-              <div className="py-8 text-center text-muted-foreground">
+              <ReviewStep
-                <p>Review step coming in next plan</p>
+                income={state.income}
-              </div>
+                selectedItems={state.selectedItems}
+                currency={currency}
+              />
             )}
 
             {/* Bottom navigation */}
             <div className="flex justify-between items-center pt-4 border-t border-border">
               <div className="flex gap-2">
                 {state.currentStep > 1 && (
-                  <Button variant="ghost" onClick={handleBack}>
+                  <Button
+                    variant="ghost"
+                    onClick={handleBack}
+                    disabled={completing}
+                  >
                     {t("setup.back")}
                   </Button>
                 )}
-                {state.currentStep < 3 && (
                 <Button
                   variant="ghost"
                   className="text-muted-foreground"
                   onClick={handleSkipStep}
+                  disabled={completing}
                 >
                   {t("setup.skip")}
                 </Button>
-                )}
               </div>
               <div>
                 {state.currentStep < 3 && (
                   <Button onClick={handleNext}>{t("setup.next")}</Button>
                 )}
                 {state.currentStep === 3 && (
-                  <Button disabled>{t("setup.complete")}</Button>
+                  <Button onClick={handleComplete} disabled={completing}>
+                    {t("setup.complete")}
+                  </Button>
                 )}
               </div>
             </div>
@@ -170,6 +279,8 @@ export default function SetupPage() {
         <button
           type="button"
           className="mt-4 text-sm text-muted-foreground underline block mx-auto"
+          onClick={handleSkipSetup}
+          disabled={completing}
         >
           {t("setup.skipSetup")}
         </button>