fix(client): preserve FTUE auth onboarding (#711)

Author: itayadler

.changeset/fix-ftue-auth-gating.md

@@ -0,0 +1,5 @@
+---
+"@frontman-ai/client": patch
+---
+
+Preserve the initial FTUE state during ACP authentication so first-time users still see onboarding instead of being treated as returning users after other client preferences are persisted.

libs/client/src/Client__ConnectionReducer.res

@@ -52,6 +52,7 @@ type state = {
   acp: acpState,
   relay: relayState,
   session: sessionState,
+  initialAuthBehavior: Client__FtueState.authBehavior,
   isSendingPrompt: bool,
   // Relay instance exists before connection completes - needed for MCPServer
   relayInstance: option<Relay.t>,
@@ -112,7 +113,11 @@ type action =
 type effect =
   | LogError(string)
   | LogInfo(string)
-  | ConnectACP({config: ACP.config, signal: WebAPI.EventAPI.abortSignal})
+  | ConnectACP({
+      config: ACP.config,
+      signal: WebAPI.EventAPI.abortSignal,
+      initialAuthBehavior: Client__FtueState.authBehavior,
+    })
   | ConnectRelay(Relay.t)
   | DisconnectRelay(Relay.t)
   | DisconnectACP(ACP.connection)
@@ -151,6 +156,7 @@ let initialState: state = {
   acp: ACPDisconnected,
   relay: RelayDisconnected,
   session: NoSession,
+  initialAuthBehavior: Client__FtueState.RedirectToLogin,
   isSendingPrompt: false,
   relayInstance: None,
   mcpServer: None,
@@ -248,13 +254,18 @@ let reduce = (state: state, action: action): (state, array<effect>) => {
         acp: ACPConnecting,
         relay: RelayConnecting,
         session: NoSession,
+        initialAuthBehavior: state.initialAuthBehavior,
         isSendingPrompt: false,
         relayInstance: Some(relay),
         mcpServer: Some(mcpServer),
         abortController: Some(abortController),
       },
       [
-        ConnectACP({config: acpConfig, signal: abortController.signal}),
+        ConnectACP({
+          config: acpConfig,
+          signal: abortController.signal,
+          initialAuthBehavior: state.initialAuthBehavior,
+        }),
         ConnectRelay(relay),
         LogInfo("Initializing connections..."),
       ],
@@ -441,7 +452,7 @@ let reduce = (state: state, action: action): (state, array<effect>) => {
     | ACPConnected(conn) => [DisconnectACP(conn)]
     | _ => []
     }
-    (initialState, Array.flat([abortEffects, relayEffects, acpEffects]))
+    ({...initialState, initialAuthBehavior: state.initialAuthBehavior}, Array.flat([abortEffects, relayEffects, acpEffects]))
 
   // === Invalid transitions ===
   | (_, Initialize(_)) => (
@@ -516,7 +527,7 @@ let handleEffect = (effect: effect, state: state, dispatch: action => unit) => {
   | AbortConnections(controller) =>
     Log.info("Aborting in-flight connections")
     WebAPI.AbortController.abort(controller)
-  | ConnectACP({config, signal}) =>
+  | ConnectACP({config, signal, initialAuthBehavior}) =>
     let connect = async () => {
       let result = await ACP.connect(config, ~signal)
       switch result {
@@ -533,12 +544,10 @@ let handleEffect = (effect: effect, state: state, dispatch: action => unit) => {
               WebAPI.Global.window->WebAPI.Window.location->WebAPI.Location.href
             let returnTo = encodeURIComponent(currentUrl)
             let fullUrl = `${loginUrl}?return_to=${returnTo}`
-            // For first-time users, surface the auth URL so the UI can show a welcome modal.
-            // Returning users get redirected immediately.
-            switch Client__FtueState.get() {
-            | Client__FtueState.New =>
+            switch initialAuthBehavior {
+            | Client__FtueState.ShowWelcomeModal =>
               dispatch(ACPConnectError(`auth_required:${fullUrl}`))
-            | Client__FtueState.WelcomeShown | Client__FtueState.Completed =>
+            | Client__FtueState.RedirectToLogin =>
               WebAPI.Global.window->WebAPI.Window.location->WebAPI.Location.assign(fullUrl)
             }
           | ACP.ConnectionFailed(msg) => dispatch(ACPConnectError(msg))

libs/client/src/Client__FrontmanProvider.res

@@ -190,7 +190,11 @@ module Provider = {
     })
 
     // Use StateReducer - effects are executed in useEffect, not during dispatch
-    let (state, dispatch) = StateReducer.useReducer(module(Reducer), Reducer.initialState)
+    let initialConnectionState = {
+      ...Reducer.initialState,
+      initialAuthBehavior: Client__FtueState.getAuthBehavior(),
+    }
+    let (state, dispatch) = StateReducer.useReducer(module(Reducer), initialConnectionState)
 
     // Single initialization effect
     React.useEffect0(() => {

libs/client/src/Client__FtueState.res

@@ -16,6 +16,10 @@ type t =
   | WelcomeShown
   | Completed
 
+type authBehavior =
+  | ShowWelcomeModal
+  | RedirectToLogin
+
 // Check whether any other frontman:* localStorage key exists, indicating a returning user
 let hasExistingFrontmanData = (): bool => {
   try {
@@ -57,6 +61,13 @@ let get = (): t => {
   }
 }
 
+let getAuthBehavior = (): authBehavior => {
+  switch get() {
+  | New => ShowWelcomeModal
+  | WelcomeShown | Completed => RedirectToLogin
+  }
+}
+
 let setWelcomeShown = () => {
   FrontmanBindings.LocalStorage.setItem(storageKey, "welcome_shown")
 }

libs/client/src/styles/frontman-theme.css

@@ -262,4 +262,3 @@
 .font-ibm-plex-mono [data-code-block-header] span {
 	margin-left: 0.375rem;
 }
-

libs/client/test/Client__ConnectionReducer.test.res

@@ -4,6 +4,7 @@ module Reducer = Client__ConnectionReducer
 module ACP = FrontmanAiFrontmanClient.FrontmanClient__ACP
 module Relay = FrontmanAiFrontmanClient.FrontmanClient__Relay
 module MCPServer = FrontmanAiFrontmanClient.FrontmanClient__MCP__Server
+module FtueState = Client__FtueState
 
 // Helper to check if effect list contains a specific effect type
 let hasEffect = (effects, predicate) => effects->Array.some(predicate)
@@ -35,6 +36,13 @@ let hasConnectRelay = effects =>
     | _ => false
     }
   )
+let getConnectACPInitialAuthBehavior = effects =>
+  effects->Array.findMap(e =>
+    switch e {
+    | Reducer.ConnectACP({initialAuthBehavior}) => Some(initialAuthBehavior)
+    | _ => None
+    }
+  )
 
 describe("Connection Reducer", () => {
   describe("Initial State", () => {
@@ -82,7 +90,7 @@ describe("Connection Reducer", () => {
         _meta: JSON.Encode.object(Dict.fromArray([("framework", JSON.Encode.string("test"))])),
       }
       let (nextState, effects) = Reducer.reduce(
-        Reducer.initialState,
+        {...Reducer.initialState, initialAuthBehavior: FtueState.ShowWelcomeModal},
         Initialize({config: mockConfig, relay: mockRelay, mcpServer: mockServer}),
       )
 
@@ -91,6 +99,7 @@ describe("Connection Reducer", () => {
       t->expect(Option.isSome(nextState.relayInstance))->Expect.toBe(true)
       t->expect(Option.isSome(nextState.mcpServer))->Expect.toBe(true)
       t->expect(hasConnectACP(effects))->Expect.toBe(true)
+      t->expect(getConnectACPInitialAuthBehavior(effects))->Expect.toBe(Some(FtueState.ShowWelcomeModal))
       t->expect(hasConnectRelay(effects))->Expect.toBe(true)
     })
 
@@ -403,6 +412,7 @@ describe("Connection Reducer", () => {
         acp: ACPConnected(mockConn),
         relay: RelayConnected,
         session: SessionActive(mockSession),
+        initialAuthBehavior: FtueState.ShowWelcomeModal,
         isSendingPrompt: false,
         relayInstance: Some(mockRelay),
         mcpServer: Some(mockServer),