@alumbwe/anvil 1.0.0

package/src/hooks/use-agent-validation.ts

@@ -0,0 +1,74 @@
+import { isDirectDeepSeekMode } from '@anvil/common/constants/deepseek-direct'
+import { validateAgents } from '@anvil/sdk'
+import { useCallback, useState } from 'react'
+
+import { loadAgentDefinitions } from '../utils/local-agent-registry'
+import { logger } from '../utils/logger'
+import { filterNetworkErrors } from '../utils/validation-error-helpers'
+
+export type ValidationError = {
+  id: string
+  message: string
+}
+
+export type ValidationCheckResult = {
+  success: boolean
+  errors: ValidationError[]
+}
+
+type UseAgentValidationResult = {
+  validationErrors: ValidationError[]
+  isValidating: boolean
+  validate: () => Promise<ValidationCheckResult>
+}
+
+/**
+ * Hook that provides agent validation functionality.
+ * Call validate() manually to trigger validation (e.g., on message send).
+ */
+export const useAgentValidation = (): UseAgentValidationResult => {
+  const [validationErrors, setValidationErrors] = useState<ValidationError[]>(
+    [],
+  )
+  const [isValidating, setIsValidating] = useState(false)
+
+  // Validate agents and update state
+  // Returns validation result with success status and any errors
+  const validate = useCallback(async (): Promise<ValidationCheckResult> => {
+    setIsValidating(true)
+
+    try {
+      const agentDefinitions = loadAgentDefinitions()
+
+      const validationResult = await validateAgents(agentDefinitions, {
+        // Remote validation hits the Anvil backend; skip it in
+        // direct-to-DeepSeek mode so sending isn't blocked by a dead endpoint.
+        remote: !isDirectDeepSeekMode(),
+      })
+
+      if (validationResult.success) {
+        setValidationErrors([])
+        return { success: true, errors: [] }
+      } else {
+        const filteredValidationErrors = filterNetworkErrors(
+          validationResult.validationErrors,
+        )
+        setValidationErrors(filteredValidationErrors)
+        return { success: false, errors: filteredValidationErrors }
+      }
+    } catch (error) {
+      logger.error({ error }, 'Agent validation failed with exception')
+      // Don't update validation errors on exception - keep previous state
+      // Return failure to block message sending on validation errors
+      return { success: false, errors: [] }
+    } finally {
+      setIsValidating(false)
+    }
+  }, [])
+
+  return {
+    validationErrors,
+    isValidating,
+    validate,
+  }
+}

package/src/hooks/use-ask-user-bridge.ts

@@ -0,0 +1,92 @@
+import { AskUserBridge } from '@anvil/common/utils/ask-user-bridge'
+import { useEffect } from 'react'
+
+import { useChatStore } from '../state/chat-store'
+
+import type { AskUserQuestion } from '../types/store'
+
+/**
+ * Patterns that indicate a "custom" or "other" catch-all option.
+ * These are redundant since the UI automatically provides a Custom text input.
+ */
+const REDUNDANT_OPTION_PATTERNS = [
+  /^custom$/i,
+  /^other$/i,
+  /^none\s*(of\s*the\s*above)?$/i,
+  /^something\s*else$/i,
+  /^enter\s*(my\s*)?own$/i,
+  /^type\s*(my\s*)?own$/i,
+  /^write\s*(my\s*)?own$/i,
+]
+
+/**
+ * Gets the label from an option, handling both string and object formats.
+ */
+function getOptionLabel(option: string | { label: string; description?: string }): string {
+  return typeof option === 'string' ? option : option.label
+}
+
+/**
+ * Checks if an option label matches any of the redundant "custom/other" patterns.
+ */
+function isRedundantOption(option: string | { label: string; description?: string }): boolean {
+  const label = getOptionLabel(option).trim()
+  return REDUNDANT_OPTION_PATTERNS.some((pattern) => pattern.test(label))
+}
+
+/**
+ * Filters out redundant "Custom"/"Other" options from questions.
+ * The UI already provides a Custom text input, so these are unnecessary and confusing.
+ */
+function filterRedundantOptions(questions: AskUserQuestion[]): AskUserQuestion[] {
+  return questions.map((question) => {
+    const filteredOptions = question.options.filter((option) => !isRedundantOption(option))
+    return {
+      ...question,
+      // Preserve the original array type (string[] or object[])
+      options: filteredOptions as typeof question.options,
+    }
+  })
+}
+
+export function useAskUserBridge() {
+  const setAskUserState = useChatStore((state) => state.setAskUserState)
+
+  useEffect(() => {
+    const unsubscribe = AskUserBridge.subscribe((request) => {
+      if (request) {
+        // Filter out redundant "Custom"/"Other" options since UI provides its own
+        const filteredQuestions = filterRedundantOptions(request.questions)
+        setAskUserState({
+          toolCallId: request.toolCallId,
+          questions: filteredQuestions,
+          // Initialize based on question type: multi-select → [], single-select → -1
+          selectedAnswers: filteredQuestions.map((q) => (q.multiSelect ? [] : -1)),
+          otherTexts: new Array(filteredQuestions.length).fill(''),
+        })
+      } else {
+        setAskUserState(null)
+      }
+    })
+    return unsubscribe
+  }, [setAskUserState])
+
+  const submitAnswers = (
+    answers: Array<{
+      questionIndex: number
+      selectedOption?: string
+      selectedOptions?: string[]
+      otherText?: string
+    }>
+  ) => {
+    // Don't clear input value - preserve user's input from before the questionnaire
+    AskUserBridge.submit({ answers })
+  }
+
+  const skip = () => {
+    // Don't clear input value - preserve user's input from before the questionnaire
+    AskUserBridge.submit({ skipped: true })
+  }
+
+  return { submitAnswers, skip }
+}

package/src/hooks/use-auth-query.ts

@@ -0,0 +1,253 @@
+import { createHash } from 'crypto'
+
+import { getDirectDeepSeekApiKey } from '@anvil/common/constants/deepseek-direct'
+import { getCiEnv } from '@anvil/common/env-ci'
+import {
+  getUserInfoFromApiKey as defaultGetUserInfoFromApiKey,
+  isRetryableStatusCode,
+  getErrorStatusCode,
+  createAuthError,
+  createServerError,
+  MAX_RETRIES_PER_MESSAGE,
+  RETRY_BACKOFF_BASE_DELAY_MS,
+} from '@anvil/sdk'
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+
+import {
+  getUserCredentials as defaultGetUserCredentials,
+  saveUserCredentials as defaultSaveUserCredentials,
+  logoutUser as logoutUserUtil,
+  type User,
+} from '../utils/auth'
+import { resetAnvilClient } from '../utils/anvil-client'
+import { logger as defaultLogger, loggerContext } from '../utils/logger'
+
+import type { GetUserInfoFromApiKeyFn } from '@anvil/common/types/contracts/database'
+import type { Logger } from '@anvil/common/types/contracts/logger'
+
+const getApiKeyHash = (apiKey: string): string => {
+  return createHash('sha256').update(apiKey).digest('hex')
+}
+
+// Query keys for type-safe cache management
+export const authQueryKeys = {
+  all: ['auth'] as const,
+  user: () => [...authQueryKeys.all, 'user'] as const,
+  validation: (apiKey: string) =>
+    [...authQueryKeys.all, 'validation', getApiKeyHash(apiKey)] as const,
+}
+
+interface ValidateAuthParams {
+  apiKey: string
+  getUserInfoFromApiKey?: GetUserInfoFromApiKeyFn
+  logger?: Logger
+}
+
+type ValidatedUserInfo = {
+  id: string
+  email: string
+}
+
+/**
+ * Check if an error is an authentication error (401, 403)
+ */
+function isAuthenticationError(error: unknown): boolean {
+  const statusCode = getErrorStatusCode(error)
+  return statusCode === 401 || statusCode === 403
+}
+
+/**
+ * Validates an API key by calling the backend
+ *
+ * CHANGE: Exported for testing purposes and accepts optional dependencies
+ * Previously this was not exported, making it impossible to test in isolation
+ */
+export async function validateApiKey({
+  apiKey,
+  getUserInfoFromApiKey = defaultGetUserInfoFromApiKey,
+  logger = defaultLogger,
+}: ValidateAuthParams): Promise<ValidatedUserInfo> {
+  const requestedFields = ['id', 'email'] as const
+
+  try {
+    const authResult = await getUserInfoFromApiKey({
+      apiKey,
+      fields: requestedFields,
+      logger,
+    })
+
+    if (!authResult) {
+      logger.error('❌ API key validation failed - invalid credentials')
+      throw createAuthError('Invalid API key')
+    }
+
+    return authResult
+  } catch (error) {
+    const statusCode = getErrorStatusCode(error)
+
+    if (isAuthenticationError(error)) {
+      logger.error('❌ API key validation failed - authentication error')
+      // Rethrow the original error to preserve statusCode for higher layers
+      throw error
+    }
+
+    if (statusCode !== undefined && isRetryableStatusCode(statusCode)) {
+      logger.error(
+        {
+          error: error instanceof Error ? error.message : String(error),
+          statusCode,
+        },
+        '❌ API key validation failed - network error',
+      )
+      // Rethrow the original error to preserve statusCode for higher layers
+      throw error
+    }
+
+    // Unknown error - wrap with statusCode for consistency
+    logger.error(
+      {
+        error: error instanceof Error ? error.message : String(error),
+      },
+      '❌ API key validation failed - unknown error',
+    )
+    throw createServerError('Authentication failed')
+  }
+}
+
+export interface UseAuthQueryDeps {
+  getUserCredentials?: () => User | null
+  getUserInfoFromApiKey?: GetUserInfoFromApiKeyFn
+  logger?: Logger
+}
+
+/**
+ * Hook to validate authentication status
+ * Uses stored credentials if available, otherwise checks environment variable
+ *
+ * CHANGE: Now accepts optional dependencies for testing via dependency injection
+ */
+export function useAuthQuery(deps: UseAuthQueryDeps = {}) {
+  const {
+    getUserCredentials = defaultGetUserCredentials,
+    getUserInfoFromApiKey = defaultGetUserInfoFromApiKey,
+    logger = defaultLogger,
+  } = deps
+
+  const userCredentials = getUserCredentials()
+  const apiKey =
+    userCredentials?.authToken ||
+    getCiEnv().ANVIL_API_KEY ||
+    getDirectDeepSeekApiKey() ||
+    ''
+
+  return useQuery({
+    queryKey: authQueryKeys.validation(apiKey),
+    queryFn: () => validateApiKey({ apiKey, getUserInfoFromApiKey, logger }),
+    enabled: !!apiKey,
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 10 * 60 * 1000, // 10 minutes
+    // Retry only for retryable network errors (5xx, timeouts, etc.)
+    // Don't retry authentication errors (invalid credentials)
+    retry: (failureCount, error) => {
+      const statusCode = getErrorStatusCode(error)
+      // Don't retry authentication errors - user needs to update credentials
+      if (isAuthenticationError(error)) {
+        return false
+      }
+      // Retry network errors if they're retryable and we haven't exceeded max retries
+      if (statusCode !== undefined && isRetryableStatusCode(statusCode)) {
+        return failureCount < MAX_RETRIES_PER_MESSAGE
+      }
+      // Don't retry other errors
+      return false
+    },
+    retryDelay: (attemptIndex) => {
+      // Exponential backoff: 1s, 2s, 4s
+      return Math.min(
+        RETRY_BACKOFF_BASE_DELAY_MS * Math.pow(2, attemptIndex),
+        8000, // Cap at 8 seconds
+      )
+    },
+  })
+}
+
+export interface UseLoginMutationDeps {
+  saveUserCredentials?: (user: User) => void
+  getUserInfoFromApiKey?: GetUserInfoFromApiKeyFn
+  logger?: Logger
+}
+
+/**
+ * Hook for login mutation
+ *
+ * CHANGE: Now accepts optional dependencies for testing via dependency injection
+ */
+export function useLoginMutation(deps: UseLoginMutationDeps = {}) {
+  const queryClient = useQueryClient()
+  const {
+    saveUserCredentials = defaultSaveUserCredentials,
+    getUserInfoFromApiKey = defaultGetUserInfoFromApiKey,
+    logger = defaultLogger,
+  } = deps
+
+  return useMutation({
+    mutationFn: async (user: User) => {
+      // Save credentials to file system
+      saveUserCredentials(user)
+
+      // Validate the new credentials
+      const authResult = await validateApiKey({
+        apiKey: user.authToken,
+        getUserInfoFromApiKey,
+        logger,
+      })
+
+      const mergedUser = { ...user, ...authResult }
+      return mergedUser
+    },
+    onSuccess: () => {
+      // Invalidate auth queries to trigger refetch with new credentials
+      queryClient.invalidateQueries({ queryKey: authQueryKeys.all })
+    },
+    onError: (error) => {
+      logger.error(
+        {
+          error: error instanceof Error ? error.message : String(error),
+          errorStack: error instanceof Error ? error.stack : undefined,
+        },
+        '❌ Login mutation failed',
+      )
+    },
+  })
+}
+
+export interface UseLogoutMutationDeps {
+  logoutUser?: () => Promise<boolean>
+  logger?: Logger
+}
+
+/**
+ * Hook for logout mutation
+ *
+ * CHANGE: Now accepts optional dependencies for testing via dependency injection
+ */
+export function useLogoutMutation(deps: UseLogoutMutationDeps = {}) {
+  const queryClient = useQueryClient()
+  const { logoutUser = logoutUserUtil, logger = defaultLogger } = deps
+
+  return useMutation({
+    mutationFn: logoutUser,
+    onSuccess: () => {
+      // Reset the SDK client after logout
+      resetAnvilClient()
+      // Clear all auth-related cache
+      queryClient.removeQueries({ queryKey: authQueryKeys.all })
+      // Clear logger context
+      delete loggerContext.userId
+      delete loggerContext.userEmail
+    },
+    onError: (error) => {
+      logger.error(error, 'Logout failed')
+    },
+  })
+}

package/src/hooks/use-auth-state.ts

@@ -0,0 +1,152 @@
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+import { useCallback, useEffect, useState } from 'react'
+
+import { useAuthQuery, useLogoutMutation } from './use-auth-query'
+import { useLoginStore } from '../state/login-store'
+import { identifyUser, trackEvent } from '../utils/analytics'
+import { getUserCredentials } from '../utils/auth'
+import { resetAnvilClient } from '../utils/anvil-client'
+import { IS_FREEBUFF } from '../utils/constants'
+import { loggerContext } from '../utils/logger'
+
+import type { MultilineInputHandle } from '../components/multiline-input'
+import type { User } from '../utils/auth'
+
+const setAuthLoggerContext = (params: { userId: string; email: string }) => {
+  loggerContext.userId = params.userId
+  loggerContext.userEmail = params.email
+  identifyUser(params.userId, { email: params.email, freebuff: IS_FREEBUFF })
+}
+
+const clearAuthLoggerContext = () => {
+  delete loggerContext.userId
+  delete loggerContext.userEmail
+}
+
+interface UseAuthStateOptions {
+  requireAuth: boolean | null
+  inputRef: React.MutableRefObject<MultilineInputHandle | null>
+  setInputFocused: (focused: boolean) => void
+  resetChatStore: () => void
+}
+
+export const useAuthState = ({
+  requireAuth,
+  inputRef,
+  setInputFocused,
+  resetChatStore,
+}: UseAuthStateOptions) => {
+  const authQuery = useAuthQuery()
+  const logoutMutation = useLogoutMutation()
+  const { resetLoginState } = useLoginStore()
+
+  const initialAuthState = requireAuth === null ? null : !requireAuth
+  const [isAuthenticated, setIsAuthenticated] = useState<boolean | null>(
+    initialAuthState,
+  )
+  const [user, setUser] = useState<User | null>(null)
+
+  // Update authentication state when requireAuth changes
+  useEffect(() => {
+    if (requireAuth === null) {
+      return
+    }
+    setIsAuthenticated(!requireAuth)
+  }, [requireAuth])
+
+  // Update authentication state based on query results
+  useEffect(() => {
+    if (authQuery.isSuccess && authQuery.data) {
+      setIsAuthenticated(true)
+      if (!user) {
+        const userCredentials = getUserCredentials()
+        const userData: User = {
+          id: authQuery.data.id,
+          name: userCredentials?.name || '',
+          email: authQuery.data.email || '',
+          authToken: userCredentials?.authToken || '',
+        }
+        setUser(userData)
+        // Identify first so the login event is attributed to the real user id
+        // and the pre-login anonymous history is aliased in.
+        setAuthLoggerContext({
+          userId: authQuery.data.id,
+          email: authQuery.data.email || '',
+        })
+        // Returning users restore an existing session instead of going through
+        // the login modal, so `cli.login` would otherwise never fire for them —
+        // making them look like a login-step drop-off in the funnel even though
+        // they're authenticated. Emit it here too, tagged by `via`.
+        trackEvent(AnalyticsEvent.LOGIN, {
+          userId: authQuery.data.id,
+          via: 'session_restore',
+          hasEmail: Boolean(authQuery.data.email),
+          hasName: Boolean(userCredentials?.name),
+        })
+      }
+    } else if (authQuery.isError) {
+      setIsAuthenticated(false)
+      setUser(null)
+      clearAuthLoggerContext()
+    }
+  }, [authQuery.isSuccess, authQuery.isError, authQuery.data, user])
+
+  // Handle successful login
+  const handleLoginSuccess = useCallback(
+    (loggedInUser: User) => {
+      // Identify first (aliases the pre-login anonymous history to the real
+      // user id) so the login event below is attributed to the user.
+      if (loggedInUser.id && loggedInUser.email) {
+        setAuthLoggerContext({
+          userId: loggedInUser.id,
+          email: loggedInUser.email,
+        })
+      }
+
+      // Track successful login
+      trackEvent(AnalyticsEvent.LOGIN, {
+        userId: loggedInUser.id,
+        via: 'modal',
+        hasEmail: Boolean(loggedInUser.email),
+        hasName: Boolean(loggedInUser.name),
+      })
+
+      // Reset the SDK client to pick up new credentials
+      resetAnvilClient()
+      resetChatStore()
+      resetLoginState()
+      setInputFocused(true)
+      setUser(loggedInUser)
+      setIsAuthenticated(true)
+    },
+    [resetChatStore, resetLoginState, setInputFocused],
+  )
+
+  // Auto-focus input after authentication
+  useEffect(() => {
+    if (isAuthenticated !== true) return
+
+    setInputFocused(true)
+
+    const focusNow = () => {
+      const handle = inputRef.current
+      if (handle && typeof handle.focus === 'function') {
+        handle.focus()
+      }
+    }
+
+    focusNow()
+    const timeoutId = setTimeout(focusNow, 0)
+
+    return () => clearTimeout(timeoutId)
+  }, [isAuthenticated, setInputFocused, inputRef])
+
+  return {
+    isAuthenticated,
+    setIsAuthenticated,
+    user,
+    setUser,
+    handleLoginSuccess,
+    logoutMutation,
+  }
+}

package/src/hooks/use-chat-input.ts

@@ -0,0 +1,105 @@
+import { useCallback, useEffect } from 'react'
+import stringWidth from 'string-width'
+
+import { useChatStore } from '../state/chat-store'
+import { IS_FREEBUFF } from '../utils/constants'
+
+import type { InputValue } from '../types/store'
+import type { AgentMode } from '../utils/constants'
+
+interface UseChatInputOptions {
+  setInputValue: (value: InputValue) => void
+  agentMode: AgentMode
+  setAgentMode: (mode: AgentMode) => void
+  separatorWidth: number
+  consumeInitialPrompt: () => string | null
+  onSubmitPrompt: (content: string, mode: AgentMode) => void | Promise<unknown>
+  isCompactHeight: boolean
+  isNarrowWidth: boolean
+}
+
+const BUILD_IT_TEXT = 'Build it!'
+
+export const useChatInput = ({
+  setInputValue,
+  agentMode,
+  setAgentMode,
+  separatorWidth,
+  consumeInitialPrompt,
+  onSubmitPrompt,
+  isCompactHeight,
+  isNarrowWidth,
+}: UseChatInputOptions) => {
+  const inputMode = useChatStore((state) => state.inputMode)
+
+  // Estimate the collapsed toggle width as rendered by AgentModeToggle.
+  // In Freebuff, the toggle is always hidden, so never reserve width for it.
+  // In non-Freebuff: hide in bash mode, compact height, or narrow width.
+  const estimatedToggleWidth =
+    IS_FREEBUFF || inputMode !== 'default' || isCompactHeight || isNarrowWidth
+      ? 0
+      : stringWidth(`< ${agentMode}`) + 6 // 2 padding + 2 borders + 2 gap
+
+  // The content box that wraps the input row has paddingLeft/paddingRight = 1
+  // (see cli/src/chat.tsx). Subtract those columns so our MultilineInput width
+  // matches the true drawable area between the borders.
+  const contentPadding = 2 // 1 left + 1 right padding
+  const availableContentWidth = Math.max(1, separatorWidth - contentPadding)
+  const inputWidth = Math.max(1, availableContentWidth - estimatedToggleWidth)
+
+  const handleBuildFast = useCallback(() => {
+    setAgentMode('DEFAULT')
+    setInputValue({
+      text: BUILD_IT_TEXT,
+      cursorPosition: BUILD_IT_TEXT.length,
+      lastEditDueToNav: true,
+    })
+    setTimeout(() => {
+      onSubmitPrompt(BUILD_IT_TEXT, 'DEFAULT')
+      setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
+    }, 0)
+  }, [setAgentMode, setInputValue, onSubmitPrompt])
+
+  const handleBuildMax = useCallback(() => {
+    setAgentMode('MAX')
+    setInputValue({
+      text: BUILD_IT_TEXT,
+      cursorPosition: BUILD_IT_TEXT.length,
+      lastEditDueToNav: true,
+    })
+    setTimeout(() => {
+      onSubmitPrompt('Build it!', 'MAX')
+      setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
+    }, 0)
+  }, [setAgentMode, setInputValue, onSubmitPrompt])
+
+  const handleBuildLite = useCallback(() => {
+    setAgentMode('LITE')
+    setInputValue({
+      text: BUILD_IT_TEXT,
+      cursorPosition: BUILD_IT_TEXT.length,
+      lastEditDueToNav: true,
+    })
+    setTimeout(() => {
+      onSubmitPrompt(BUILD_IT_TEXT, 'LITE')
+      setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
+    }, 0)
+  }, [setAgentMode, setInputValue, onSubmitPrompt])
+
+  useEffect(() => {
+    const initialPrompt = consumeInitialPrompt()
+    if (initialPrompt) {
+      setTimeout(() => {
+        onSubmitPrompt(initialPrompt, agentMode)
+      }, 100)
+    }
+    return undefined
+  }, [consumeInitialPrompt, agentMode, onSubmitPrompt])
+
+  return {
+    inputWidth,
+    handleBuildFast,
+    handleBuildMax,
+    handleBuildLite,
+  }
+}