@alumbwe/anvil 1.0.0

package/src/hooks/use-connection-status.ts

@@ -0,0 +1,142 @@
+import { useEffect, useRef, useState } from 'react'
+
+import { getAnvilClient } from '../utils/anvil-client'
+import { logger } from '../utils/logger'
+import {
+  failedPollDelayMs,
+  jitterPollIntervalMs,
+} from '../utils/polling-backoff'
+
+// Adaptive health check interval configuration
+// Progressively increases polling interval based on consecutive successful checks
+const HEALTH_CHECK_CONFIG = {
+  // Healthy startup cadence (ms).
+  INITIAL_INTERVAL: 10_000, // 10 seconds
+  // Interval thresholds based on consecutive successful checks
+  INTERVALS: [
+    { successCount: 3, interval: 30_000 }, // 30 seconds after 3 successes
+    { successCount: 6, interval: 60_000 }, // 1 minute after 6 successes
+    { successCount: 10, interval: 120_000 }, // 2 minutes after 10 successes
+    { successCount: 15, interval: 300_000 }, // 5 minutes after 15 successes
+    { successCount: 20, interval: 600_000 }, // 10 minutes after 20 successes
+  ],
+} as const
+
+/**
+ * Calculates the next health check interval based on consecutive successful checks
+ * Exported for testing purposes
+ */
+export function getNextInterval(consecutiveSuccesses: number): number {
+  // Find the highest threshold that we've passed
+  for (let i = HEALTH_CHECK_CONFIG.INTERVALS.length - 1; i >= 0; i--) {
+    const { successCount, interval } = HEALTH_CHECK_CONFIG.INTERVALS[i]
+    if (consecutiveSuccesses >= successCount) {
+      return interval
+    }
+  }
+  return HEALTH_CHECK_CONFIG.INITIAL_INTERVAL
+}
+
+/**
+ * Hook to monitor connection status to the Anvil backend.
+ * Jitters the adaptive healthy cadence and exponentially backs off failures so
+ * a shared outage cannot synchronize every CLI into a fixed retry wave.
+ *
+ * When the connection transitions from disconnected to connected, the optional
+ * onReconnect callback is invoked with a boolean indicating whether this was
+ * the initial connection (true) or a subsequent reconnection (false).
+ */
+export const useConnectionStatus = (
+  onReconnect?: (isInitialConnection: boolean) => void,
+) => {
+  const [isConnected, setIsConnected] = useState(true)
+  // null = never connected, false = was disconnected, true = was connected
+  const previousConnectedRef = useRef<boolean | null>(null)
+
+  useEffect(() => {
+    let isMounted = true
+    let timeoutId: NodeJS.Timeout | null = null
+    let consecutiveSuccesses = 0
+    let consecutiveFailures = 0
+
+    const scheduleNextCheck = (interval: number) => {
+      if (!isMounted) return
+      timeoutId = setTimeout(() => checkConnection(), interval)
+    }
+
+    const scheduleFailedCheck = (message: string, error?: unknown): void => {
+      if (!isMounted) return
+      setIsConnected(false)
+      previousConnectedRef.current = false
+      consecutiveSuccesses = 0
+      consecutiveFailures++
+      const delayMs = failedPollDelayMs({
+        consecutiveFailures,
+      })
+      logger.debug(
+        {
+          ...(error === undefined ? {} : { error }),
+          delayMs,
+          consecutiveFailures,
+        },
+        message,
+      )
+      scheduleNextCheck(delayMs)
+    }
+
+    const checkConnection = async () => {
+      try {
+        const client = await getAnvilClient()
+        if (!client) {
+          scheduleFailedCheck('Health check: No client, backing off')
+          return
+        }
+
+        const connected = await client.checkConnection()
+        if (!isMounted) return
+
+        const prevConnected = previousConnectedRef.current
+        setIsConnected(connected)
+        previousConnectedRef.current = connected
+
+        if (connected) {
+          consecutiveFailures = 0
+          // Determine if this is the initial connection (null) or a reconnection (false)
+          const isInitialConnection = prevConnected === null
+          const shouldFireReconnectCallback =
+            typeof onReconnect === 'function' && prevConnected !== true
+
+          if (shouldFireReconnectCallback) {
+            logger.info(
+              { isInitialConnection },
+              'Reconnection detected, firing onReconnect callback',
+            )
+            onReconnect(isInitialConnection)
+          }
+          consecutiveSuccesses++
+          scheduleNextCheck(
+            jitterPollIntervalMs({
+              intervalMs: getNextInterval(consecutiveSuccesses),
+            }),
+          )
+        } else {
+          scheduleFailedCheck('Health check failed, backing off')
+        }
+      } catch (error) {
+        scheduleFailedCheck('Connection check failed; backing off', error)
+      }
+    }
+
+    // Start first check immediately
+    checkConnection()
+
+    return () => {
+      isMounted = false
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
+    }
+  }, [])
+
+  return isConnected
+}

package/src/hooks/use-directory-browser.ts

@@ -0,0 +1,88 @@
+import { existsSync, statSync } from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { useCallback, useMemo, useState } from 'react'
+
+import { getDirectories, hasGitDirectory } from '../utils/directory-browser'
+
+import type { DirectoryEntry } from '../utils/directory-browser'
+
+export interface UseDirectoryBrowserOptions {
+  /** Initial path to browse from (defaults to home directory) */
+  initialPath?: string
+}
+
+export interface UseDirectoryBrowserReturn {
+  /** Current directory path */
+  currentPath: string
+  /** Set the current directory path */
+  setCurrentPath: (path: string) => void
+  /** List of directory entries in the current path */
+  directories: DirectoryEntry[]
+  /** Whether current directory is a git repository */
+  isGitRepo: boolean
+  /** Expand ~ to home directory */
+  expandPath: (inputPath: string) => string
+  /** Try to navigate to a typed path, returns true if successful */
+  tryNavigateToPath: (inputPath: string) => boolean
+  /** Navigate to a directory entry */
+  navigateToDirectory: (entry: DirectoryEntry) => void
+}
+
+/**
+ * Hook for directory browsing state and navigation.
+ * Provides current path state, directory listing, git detection,
+ * and navigation utilities.
+ */
+export function useDirectoryBrowser({
+  initialPath,
+}: UseDirectoryBrowserOptions = {}): UseDirectoryBrowserReturn {
+  const [currentPath, setCurrentPath] = useState(initialPath ?? os.homedir())
+
+  // Get directories for current path
+  const directories = useMemo(() => getDirectories(currentPath), [currentPath])
+
+  // Check if current directory has .git
+  const isGitRepo = useMemo(() => hasGitDirectory(currentPath), [currentPath])
+
+  // Expand ~ to home directory
+  const expandPath = useCallback((inputPath: string): string => {
+    if (inputPath.startsWith('~')) {
+      return path.join(os.homedir(), inputPath.slice(1))
+    }
+    return inputPath
+  }, [])
+
+  // Try to navigate to a typed path
+  const tryNavigateToPath = useCallback(
+    (inputPath: string): boolean => {
+      const expandedPath = expandPath(inputPath.trim())
+      try {
+        if (existsSync(expandedPath) && statSync(expandedPath).isDirectory()) {
+          setCurrentPath(expandedPath)
+          return true
+        }
+      } catch {
+        // Path doesn't exist or can't be accessed
+      }
+      return false
+    },
+    [expandPath],
+  )
+
+  // Navigate to a directory entry
+  const navigateToDirectory = useCallback((entry: DirectoryEntry) => {
+    setCurrentPath(entry.path)
+  }, [])
+
+  return {
+    currentPath,
+    setCurrentPath,
+    directories,
+    isGitRepo,
+    expandPath,
+    tryNavigateToPath,
+    navigateToDirectory,
+  }
+}

package/src/hooks/use-elapsed-time.ts

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+export interface ElapsedTimeTracker {
+  /**
+   * Start tracking elapsed time from now
+   */
+  start: () => void
+  /**
+   * Stop tracking and reset to 0
+   */
+  stop: () => void
+  /**
+   * Pause tracking, freezing the current elapsed time
+   */
+  pause: () => void
+  /**
+   * Resume tracking from the frozen elapsed time
+   */
+  resume: () => void
+  /**
+   * Get the current elapsed seconds
+   */
+  elapsedSeconds: number
+  /**
+   * Get the start time timestamp (null if not started)
+   */
+  startTime: number | null
+  /**
+   * Whether the timer is currently paused
+   */
+  isPaused: boolean
+}
+
+/**
+ * Hook to track elapsed time with manual start/stop control
+ * Updates every second while active
+ *
+ * @returns ElapsedTimeTracker - Object with start/stop methods and current elapsed time
+ *
+ * @example
+ * const timer = useElapsedTime()
+ * timer.start() // Start timing
+ * timer.stop()  // Stop and reset
+ *
+ * // Pass the timer object to components that need to display elapsed time
+ * <StatusIndicator timer={timer} />
+ * <MessageBlock timer={timer} />
+ */
+export const useElapsedTime = (): ElapsedTimeTracker => {
+  const [startTime, setStartTime] = useState<number | null>(null)
+  const [elapsedSeconds, setElapsedSeconds] = useState<number>(0)
+  const [isPaused, setIsPaused] = useState(false)
+  // Track accumulated time from previous pause/resume cycles
+  const [accumulatedSeconds, setAccumulatedSeconds] = useState(0)
+
+  const start = useCallback(() => {
+    setStartTime(Date.now())
+    setAccumulatedSeconds(0)
+    setIsPaused(false)
+  }, [])
+
+  const stop = useCallback(() => {
+    setStartTime(null)
+    setElapsedSeconds(0)
+    setAccumulatedSeconds(0)
+    setIsPaused(false)
+  }, [])
+
+  const pause = useCallback(() => {
+    if (startTime && !isPaused) {
+      // Capture current elapsed time before pausing
+      const currentElapsed = Math.floor((Date.now() - startTime) / 1000)
+      setAccumulatedSeconds(currentElapsed)
+      setElapsedSeconds(currentElapsed)
+      setIsPaused(true)
+    }
+  }, [startTime, isPaused])
+
+  const resume = useCallback(() => {
+    if (isPaused) {
+      // Set a new start time adjusted for accumulated time
+      setStartTime(Date.now() - accumulatedSeconds * 1000)
+      setIsPaused(false)
+    }
+  }, [isPaused, accumulatedSeconds])
+
+  useEffect(() => {
+    if (!startTime || isPaused) {
+      // When paused, keep showing the frozen elapsed time (don't reset)
+      if (!isPaused && !startTime) {
+        setElapsedSeconds(0)
+      }
+      return
+    }
+
+    const updateElapsed = () => {
+      const elapsed = Math.floor((Date.now() - startTime) / 1000)
+      setElapsedSeconds(elapsed)
+    }
+
+    // Update immediately
+    updateElapsed()
+
+    // Then update every second
+    const interval = setInterval(updateElapsed, 1000)
+
+    return () => clearInterval(interval)
+  }, [startTime, isPaused])
+
+  const timer = useMemo(
+    () => ({ start, stop, pause, resume, elapsedSeconds, startTime, isPaused }),
+    [start, stop, pause, resume, elapsedSeconds, startTime, isPaused],
+  )
+
+  return timer
+}

package/src/hooks/use-event.ts

@@ -0,0 +1,34 @@
+import { useCallback, useRef } from 'react'
+
+/**
+ * Returns a stable function reference that always calls the latest version of the provided callback.
+ * Similar to React's proposed useEvent RFC.
+ *
+ * The returned function has a stable identity across renders, but always calls the most recent
+ * version of the callback you pass in. This is useful for event handlers and callbacks that
+ * need to access the latest props/state without causing re-renders of child components.
+ *
+ * @param callback - The function to wrap
+ * @returns A stable function reference that calls the latest version of the callback
+ *
+ * @example
+ * const handleClick = useEvent(() => {
+ *   console.log(count) // Always logs the latest count
+ * })
+ *
+ * // handleClick has a stable reference, so it won't cause child re-renders
+ * <ChildComponent onClick={handleClick} />
+ */
+export function useEvent<T extends (...args: any[]) => any>(callback: T): T {
+  const callbackRef = useRef<T>(callback)
+
+  // Update the ref to the latest callback on every render
+  // This ensures the ref is always in sync with the current render
+  callbackRef.current = callback
+
+  // Return a stable function that calls the latest callback
+  return useCallback(
+    ((...args: any[]) => callbackRef.current(...args)) as T,
+    [], // Empty deps array ensures the function identity is stable
+  )
+}

package/src/hooks/use-exit-handler.ts

@@ -0,0 +1,66 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import { getCurrentChatId } from '../project-files'
+import { IS_FREEBUFF } from '../utils/constants'
+import { exitCliCleanly } from '../utils/exit-cleanly'
+
+import type { InputValue } from '../types/store'
+
+interface UseExitHandlerOptions {
+  inputValue: string
+  setInputValue: (value: InputValue) => void
+}
+
+let exitHandlerRegistered = false
+
+function setupExitMessageHandler() {
+  if (exitHandlerRegistered) return
+  exitHandlerRegistered = true
+
+  process.on('exit', () => {
+    try {
+      const chatId = getCurrentChatId()
+      if (chatId) {
+        // This runs synchronously during the exit phase
+        // OpenTUI has already cleaned up by this point
+        const cliName = IS_FREEBUFF ? 'freebuff' : 'anvil'
+        process.stdout.write(
+          `\nTo continue this session later, run:\n${cliName} --continue ${chatId}\n`,
+        )
+      }
+    } catch {
+      // Silent fail - don't block exit
+    }
+  })
+}
+
+export const useExitHandler = ({
+  inputValue,
+  setInputValue,
+}: UseExitHandlerOptions) => {
+  const [nextCtrlCWillExit, setNextCtrlCWillExit] = useState(false)
+
+  useEffect(() => {
+    setupExitMessageHandler()
+  }, [])
+
+  const handleCtrlC = useCallback(() => {
+    if (inputValue) {
+      setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
+      return true
+    }
+
+    if (!nextCtrlCWillExit) {
+      setNextCtrlCWillExit(true)
+      setTimeout(() => {
+        setNextCtrlCWillExit(false)
+      }, 2000)
+      return true
+    }
+
+    void exitCliCleanly()
+    return true
+  }, [inputValue, setInputValue, nextCtrlCWillExit])
+
+  return { handleCtrlC, nextCtrlCWillExit }
+}

package/src/hooks/use-fetch-login-url.ts

@@ -0,0 +1,65 @@
+import { useMutation } from '@tanstack/react-query'
+import { safeOpen } from '../utils/open-url'
+
+import { LOGIN_WEBSITE_URL } from '../login/constants'
+import { generateLoginUrl } from '../login/login-flow'
+import { trackEvent } from '../utils/analytics'
+import { logger } from '../utils/logger'
+
+interface UseFetchLoginUrlParams {
+  setLoginUrl: (url: string | null) => void
+  setFingerprintHash: (hash: string | null) => void
+  setExpiresAt: (expiresAt: string | null) => void
+  setIsWaitingForEnter: (waiting: boolean) => void
+  setHasOpenedBrowser: (opened: boolean) => void
+  setError: (error: string | null) => void
+}
+
+/**
+ * Custom hook that handles fetching the login URL and opening the browser
+ */
+export function useFetchLoginUrl({
+  setLoginUrl,
+  setFingerprintHash,
+  setExpiresAt,
+  setIsWaitingForEnter,
+  setHasOpenedBrowser,
+  setError,
+}: UseFetchLoginUrlParams) {
+  const fetchLoginUrlMutation = useMutation({
+    mutationFn: async (fingerprintId: string) => {
+      return generateLoginUrl(
+        {
+          logger,
+          trackEvent,
+        },
+        {
+          baseUrl: LOGIN_WEBSITE_URL,
+          fingerprintId,
+          via: 'modal',
+        },
+      )
+    },
+    onSuccess: async (data) => {
+      setLoginUrl(data.loginUrl)
+      setFingerprintHash(data.fingerprintHash)
+      setExpiresAt(data.expiresAt)
+      setIsWaitingForEnter(true)
+      setHasOpenedBrowser(true)
+
+      // Open browser after fetching URL
+      await safeOpen(data.loginUrl)
+    },
+    onError: (err) => {
+      setError(err instanceof Error ? err.message : 'Failed to get login URL')
+      logger.error(
+        {
+          error: err instanceof Error ? err.message : String(err),
+        },
+        'Failed to get login URL',
+      )
+    },
+  })
+
+  return fetchLoginUrlMutation
+}

package/src/hooks/use-fingerprint.ts

@@ -0,0 +1,61 @@
+import { useEffect, useState } from 'react'
+
+import { calculateFingerprint, generateFingerprintIdSync } from '../utils/fingerprint'
+import { logger } from '../utils/logger'
+
+interface UseFingerprintResult {
+  fingerprintId: string
+  isEnhanced: boolean
+  isLoading: boolean
+}
+
+/**
+ * React hook for generating a hardware-based fingerprint.
+ *
+ * Immediately provides a legacy fingerprint for responsiveness,
+ * then asynchronously generates an enhanced fingerprint if possible.
+ *
+ * The fingerprint is stable across re-renders (generated once on mount).
+ */
+export function useFingerprint(): UseFingerprintResult {
+  // Start with a sync legacy fingerprint for immediate availability
+  const [state, setState] = useState<UseFingerprintResult>(() => ({
+    fingerprintId: generateFingerprintIdSync(),
+    isEnhanced: false,
+    isLoading: true,
+  }))
+
+  useEffect(() => {
+    let cancelled = false
+
+    const generateEnhanced = async () => {
+      try {
+        const enhancedFingerprint = await calculateFingerprint()
+        if (!cancelled) {
+          setState({
+            fingerprintId: enhancedFingerprint,
+            isEnhanced: enhancedFingerprint.startsWith('enhanced-'),
+            isLoading: false,
+          })
+        }
+      } catch (error) {
+        logger.error(error, 'Failed to generate enhanced fingerprint')
+        if (!cancelled) {
+          // Keep the legacy fingerprint we already have
+          setState((prev) => ({
+            ...prev,
+            isLoading: false,
+          }))
+        }
+      }
+    }
+
+    generateEnhanced()
+
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  return state
+}

package/src/hooks/use-freebuff-ctrl-c-exit.ts

@@ -0,0 +1,23 @@
+import { useKeyboard } from '@opentui/react'
+import { useCallback } from 'react'
+
+import { exitCliCleanly } from '../utils/exit-cleanly'
+
+import type { KeyEvent } from '@opentui/core'
+
+/**
+ * Bind Ctrl+C on a full-screen freebuff view to `exitCliCleanly`. Stdin
+ * is in raw mode, so SIGINT never fires — the key arrives as a normal OpenTUI
+ * key event and we route it through the shared cleanup path (flush analytics,
+ * release the session seat, then process.exit).
+ */
+export function useFreebuffCtrlCExit(): void {
+  useKeyboard(
+    useCallback((key: KeyEvent) => {
+      if (key.ctrl && key.name === 'c') {
+        key.preventDefault?.()
+        void exitCliCleanly()
+      }
+    }, []),
+  )
+}

package/src/hooks/use-freebuff-session-progress.ts

@@ -0,0 +1,34 @@
+import { useNow } from './use-now'
+import { IS_FREEBUFF } from '../utils/constants'
+
+import type { FreebuffSessionResponse } from '../types/freebuff-session'
+
+export interface FreebuffSessionProgress {
+  /** 0..1, fraction of the session remaining. 1 at admission, 0 at expiry. */
+  fraction: number
+  remainingMs: number
+}
+
+/**
+ * Computes a live progress value for the active freebuff session, ticking at
+ * 1Hz. Returns null outside of active state or in non-freebuff builds, so
+ * callers can short-circuit their rendering.
+ */
+export function useFreebuffSessionProgress(
+  session: FreebuffSessionResponse | null,
+): FreebuffSessionProgress | null {
+  const expiresAtMs =
+    session?.status === 'active' ? Date.parse(session.expiresAt) : null
+  const admittedAtMs =
+    session?.status === 'active' ? Date.parse(session.admittedAt) : null
+
+  const nowMs = useNow(1000, expiresAtMs !== null)
+
+  if (!IS_FREEBUFF || !expiresAtMs || !admittedAtMs) return null
+
+  const totalMs = expiresAtMs - admittedAtMs
+  if (totalMs <= 0) return null
+  const remainingMs = Math.max(0, expiresAtMs - nowMs)
+  const fraction = Math.max(0, Math.min(1, remainingMs / totalMs))
+  return { fraction, remainingMs }
+}