feat(FN-1702): merge fusion/fn-1702

packages/dashboard/app/hooks/__tests__/useAuthOnboarding.test.ts

@@ -19,6 +19,8 @@ describe("useAuthOnboarding", () => {
     vi.clearAllMocks();
   });
 
+  // --- Trigger branches ---
+
   it("opens onboarding when no providers are authenticated and onboarding is incomplete", async () => {
     mockFetchAuthStatus.mockResolvedValue({
       providers: [{ id: "openai", name: "OpenAI", authenticated: false }],
@@ -44,6 +46,32 @@ describe("useAuthOnboarding", () => {
     expect(openSettings).not.toHaveBeenCalled();
   });
 
+  it("opens onboarding when modelOnboardingComplete is undefined (first-run detection)", async () => {
+    mockFetchAuthStatus.mockResolvedValue({
+      providers: [{ id: "openai", name: "OpenAI", authenticated: false }],
+    });
+    // Explicit first-run: modelOnboardingComplete is undefined (not explicitly false)
+    mockFetchGlobalSettings.mockResolvedValue({
+      modelOnboardingComplete: undefined,
+      defaultProvider: undefined,
+      defaultModelId: undefined,
+    } as never);
+
+    renderHook(() =>
+      useAuthOnboarding({
+        projectId: "proj_123",
+        openModelOnboarding,
+        openSettings,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(openModelOnboarding).toHaveBeenCalledTimes(1);
+    });
+
+    expect(openSettings).not.toHaveBeenCalled();
+  });
+
   it("opens authentication settings when onboarding is complete but no providers are authenticated", async () => {
     mockFetchAuthStatus.mockResolvedValue({
       providers: [{ id: "anthropic", name: "Anthropic", authenticated: false }],
@@ -94,6 +122,34 @@ describe("useAuthOnboarding", () => {
     expect(openSettings).not.toHaveBeenCalled();
   });
 
+  it("does NOT auto-open when authenticated provider exists and default model is configured", async () => {
+    mockFetchAuthStatus.mockResolvedValue({
+      providers: [{ id: "anthropic", name: "Anthropic", authenticated: true }],
+    });
+    mockFetchGlobalSettings.mockResolvedValue({
+      modelOnboardingComplete: true,
+      defaultProvider: "anthropic",
+      defaultModelId: "claude-sonnet-4-5",
+    } as never);
+
+    renderHook(() =>
+      useAuthOnboarding({
+        projectId: "proj_123",
+        openModelOnboarding,
+        openSettings,
+      }),
+    );
+
+    // Give time for any async calls to resolve
+    await waitFor(() => {
+      expect(mockFetchAuthStatus).toHaveBeenCalledTimes(1);
+    });
+
+    // Neither onboarding nor settings should open
+    expect(openModelOnboarding).not.toHaveBeenCalled();
+    expect(openSettings).not.toHaveBeenCalled();
+  });
+
   it("does nothing when auth status fetch fails", async () => {
     mockFetchAuthStatus.mockRejectedValueOnce(new Error("network"));
 
@@ -113,4 +169,111 @@ describe("useAuthOnboarding", () => {
     expect(openSettings).not.toHaveBeenCalled();
     expect(mockFetchGlobalSettings).not.toHaveBeenCalled();
   });
+
+  // --- One-shot guard ---
+
+  it("does not re-trigger onboarding when projectId changes after initial bootstrap", async () => {
+    mockFetchAuthStatus.mockResolvedValue({
+      providers: [{ id: "openai", name: "OpenAI", authenticated: false }],
+    });
+    mockFetchGlobalSettings.mockResolvedValue({
+      modelOnboardingComplete: false,
+      defaultProvider: undefined,
+      defaultModelId: undefined,
+    } as never);
+
+    // First render with project 1
+    const { rerender } = renderHook(
+      ({ projectId }: { projectId: string }) =>
+        useAuthOnboarding({
+          projectId,
+          openModelOnboarding,
+          openSettings,
+        }),
+      {
+        initialProps: { projectId: "proj_1" },
+      },
+    );
+
+    await waitFor(() => {
+      expect(openModelOnboarding).toHaveBeenCalledTimes(1);
+    });
+
+    // Simulate project context churn - change projectId prop
+    rerender({ projectId: "proj_2" });
+
+    // Onboarding should NOT open again (one-shot guard prevents repeat)
+    expect(openModelOnboarding).toHaveBeenCalledTimes(1);
+    expect(openSettings).not.toHaveBeenCalled();
+  });
+
+  it("does not re-trigger when openModelOnboarding reference changes", async () => {
+    mockFetchAuthStatus.mockResolvedValue({
+      providers: [{ id: "openai", name: "OpenAI", authenticated: false }],
+    });
+    mockFetchGlobalSettings.mockResolvedValue({
+      modelOnboardingComplete: false,
+      defaultProvider: undefined,
+      defaultModelId: undefined,
+    } as never);
+
+    const { rerender } = renderHook(
+      ({ open }: { open: () => void }) =>
+        useAuthOnboarding({
+          projectId: "proj_123",
+          openModelOnboarding: open,
+          openSettings,
+        }),
+      {
+        initialProps: { open: openModelOnboarding },
+      },
+    );
+
+    await waitFor(() => {
+      expect(openModelOnboarding).toHaveBeenCalledTimes(1);
+    });
+
+    // Simulate a new function reference (e.g., after modal manager re-render)
+    const newOpenOnboarding = vi.fn();
+    rerender({ open: newOpenOnboarding });
+
+    // Should NOT trigger again
+    expect(openModelOnboarding).toHaveBeenCalledTimes(1);
+    expect(newOpenOnboarding).not.toHaveBeenCalled();
+  });
+
+  it("does not re-trigger when openSettings reference changes", async () => {
+    mockFetchAuthStatus.mockResolvedValue({
+      providers: [{ id: "anthropic", name: "Anthropic", authenticated: false }],
+    });
+    mockFetchGlobalSettings.mockResolvedValue({
+      modelOnboardingComplete: true,
+      defaultProvider: "anthropic",
+      defaultModelId: "claude-sonnet-4-5",
+    } as never);
+
+    const { rerender } = renderHook(
+      ({ open }: { open: (section?: string) => void }) =>
+        useAuthOnboarding({
+          projectId: "proj_123",
+          openModelOnboarding,
+          openSettings: open,
+        }),
+      {
+        initialProps: { open: openSettings },
+      },
+    );
+
+    await waitFor(() => {
+      expect(openSettings).toHaveBeenCalledWith("authentication");
+    });
+
+    // Simulate a new function reference
+    const newOpenSettings = vi.fn();
+    rerender({ open: newOpenSettings });
+
+    // Should NOT trigger again
+    expect(openSettings).toHaveBeenCalledTimes(1);
+    expect(newOpenSettings).not.toHaveBeenCalled();
+  });
 });

packages/dashboard/app/hooks/useAuthOnboarding.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { fetchAuthStatus, fetchGlobalSettings } from "../api";
 import type { SectionId } from "../components/SettingsModal";
 
@@ -10,39 +10,73 @@ export interface UseAuthOnboardingOptions {
 
 /**
  * Runs auth/onboarding checks and opens the appropriate setup modal.
+ *
+ * This hook implements a one-shot guard: the auto-trigger logic runs at most
+ * once per hook instance (regardless of effect re-runs due to dependency changes).
+ * This prevents repeat auto-opens on incidental rerenders or project context churn.
+ *
+ * Trigger behavior:
+ * - First-run (onboarding incomplete): opens model onboarding wizard
+ * - Completed onboarding + unauthenticated providers: opens Settings → Authentication
+ * - Already configured: no auto-open
  */
 export function useAuthOnboarding({
   projectId,
   openModelOnboarding,
   openSettings,
 }: UseAuthOnboardingOptions): void {
+  // One-shot guard: prevents the auto-trigger logic from running more than once
+  // per hook instance, even if the effect re-runs due to dependency changes.
+  const hasTriggeredRef = useRef(false);
+
   useEffect(() => {
+    // Skip if we've already triggered (one-shot guard)
+    if (hasTriggeredRef.current) return;
+    // Mark as triggered immediately to prevent any race condition on re-runs
+    hasTriggeredRef.current = true;
+
+    let shouldOpenOnboarding = false;
+    let shouldOpenSettings = false;
+
     fetchAuthStatus()
       .then(({ providers }) => {
         const hasAuthenticatedProvider = providers.some((provider) => provider.authenticated);
         const needsSetup = providers.length > 0 && !hasAuthenticatedProvider;
 
         if (needsSetup || (providers.length > 0 && hasAuthenticatedProvider)) {
-          fetchGlobalSettings()
+          return fetchGlobalSettings()
             .then((globalSettings) => {
-              const hasDefaultModel = !!(globalSettings.defaultProvider && globalSettings.defaultModelId);
+              const hasDefaultModel = !!(
+                globalSettings.defaultProvider && globalSettings.defaultModelId
+              );
+              // Explicit first-run detection: onboarding is incomplete when
+              // modelOnboardingComplete is false or undefined
+              const onboardingIncomplete =
+                globalSettings.modelOnboardingComplete === false ||
+                globalSettings.modelOnboardingComplete === undefined;
               const setupIncomplete = !hasAuthenticatedProvider || !hasDefaultModel;
 
-              if (!globalSettings.modelOnboardingComplete && setupIncomplete) {
-                openModelOnboarding();
+              if (onboardingIncomplete && setupIncomplete) {
+                shouldOpenOnboarding = true;
               } else if (!hasAuthenticatedProvider) {
-                openSettings("authentication");
-              }
-            })
-            .catch(() => {
-              if (!hasAuthenticatedProvider) {
-                openModelOnboarding();
+                // Completed onboarding but no authenticated provider → fallback
+                // to Settings Authentication section
+                shouldOpenSettings = true;
               }
             });
         }
       })
+      .then(() => {
+        // Execute after the promise chain resolves
+        if (shouldOpenOnboarding) {
+          openModelOnboarding();
+        } else if (shouldOpenSettings) {
+          openSettings("authentication");
+        }
+      })
       .catch(() => {
-        // Fail silently (preserves existing App behavior).
+        // Fail silently - non-blocking behavior preserves dashboard usability.
+        // Onboarding can be manually triggered later via Settings if needed.
       });
   }, [projectId, openModelOnboarding, openSettings]);
 }