spine-framework 0.1.0

package/.framework/src/components/ui/tooltip.tsx

@@ -0,0 +1,57 @@
+"use client"
+
+import * as React from "react"
+import { Tooltip as TooltipPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "z-50 inline-flex w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }

package/.framework/src/contexts/AppContext.tsx

@@ -0,0 +1,133 @@
+import React, { createContext, useContext, useState, useEffect } from 'react'
+import { AppRecord } from '../hooks/useApps'
+import { apiFetch } from '../lib/api'
+import { useAuth } from './AuthContext'
+
+// ─── Current App Context (per-route) ───────────────────────────────────────────
+
+interface AppContextType {
+  app: AppRecord
+}
+
+const AppContext = createContext<AppContextType | undefined>(undefined)
+
+/**
+ * Returns the current app record from the nearest AppProvider.
+ * Must be called inside an AppProvider (i.e., inside an app route).
+ */
+export function useCurrentApp(): AppRecord {
+  const context = useContext(AppContext)
+  if (context === undefined) {
+    throw new Error('useCurrentApp must be used within an AppProvider')
+  }
+  return context.app
+}
+
+interface AppProviderProps {
+  app: AppRecord
+  children: React.ReactNode
+}
+
+/**
+ * Provides the current app record to all descendants via useCurrentApp().
+ */
+export function AppProvider({ app, children }: AppProviderProps) {
+  return (
+    <AppContext.Provider value={{ app }}>
+      {children}
+    </AppContext.Provider>
+  )
+}
+
+// ─── Apps Registry Context (global, fetch-once) ─────────────────────────────
+
+interface AppsRegistryContextType {
+  apps: AppRecord[]
+  routableApps: AppRecord[]
+  loading: boolean
+  error: string | null
+  refetch: () => void
+}
+
+const AppsRegistryContext = createContext<AppsRegistryContextType | undefined>(undefined)
+
+/**
+ * Returns the global apps registry (all accessible apps for this user).
+ * Fetches once on mount after auth, cached for the session.
+ * Use this instead of useApps() to avoid per-page refetches.
+ */
+export function useAppsRegistry(): AppsRegistryContextType {
+  const context = useContext(AppsRegistryContext)
+  if (context === undefined) {
+    throw new Error('useAppsRegistry must be used within an AppsRegistryProvider')
+  }
+  return context
+}
+
+interface AppsRegistryProviderProps {
+  children: React.ReactNode
+}
+
+/**
+ * Fetches all accessible apps once after authentication and provides them
+ * globally. Wrap this around AuthenticatedRouter so routes don't re-fetch
+ * on every navigation.
+ */
+export function AppsRegistryProvider({ children }: AppsRegistryProviderProps) {
+  const { user } = useAuth()
+  const [apps, setApps] = useState<AppRecord[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const fetchApps = async () => {
+    if (!user) {
+      setApps([])
+      setLoading(false)
+      return
+    }
+
+    try {
+      setLoading(true)
+      setError(null)
+
+      const response = await apiFetch('/api/apps?action=list')
+      if (!response.ok) throw new Error(`Failed to fetch apps: ${response.statusText}`)
+
+      const data = await response.json()
+      if (data.error) throw new Error(data.error)
+
+      const allApps: AppRecord[] = data.data || data || []
+
+      const accessible = allApps.filter(app => {
+        if (!app.is_active) return false
+        const requiredRoles = app.required_roles || (app.min_role ? [app.min_role] : [])
+        if (requiredRoles.length === 0) return true
+        if (!user.roles || user.roles.length === 0) return false
+        if (user.roles.includes('system_admin')) return true
+        return requiredRoles.some(role => user.roles!.includes(role))
+      })
+
+      setApps(accessible)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load apps')
+      setApps([])
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  // Fetch once when user changes (login/logout), not on every render
+  useEffect(() => {
+    fetchApps()
+  }, [user?.id, user?.account_id])
+
+  const routableApps = apps.filter(
+    app => app.route_prefix != null && app.renderer !== 'none'
+  )
+
+  return (
+    <AppsRegistryContext.Provider value={{ apps, routableApps, loading, error, refetch: fetchApps }}>
+      {children}
+    </AppsRegistryContext.Provider>
+  )
+}

package/.framework/src/contexts/AuthContext.tsx

@@ -0,0 +1,371 @@
+/**
+ * @module src/contexts/AuthContext
+ * @audience installer
+ * @layer frontend-hook
+ * @stability stable
+ *
+ * React authentication context and provider for the Spine frontend.
+ * Manages the full Supabase auth lifecycle: initial session hydration,
+ * login, logout, auth state change events, and a server-side user context
+ * fetch (principal, account, roles, permissions).
+ *
+ * **Session hydration strategy:**
+ * 1. On mount, restore user from `sessionStorage` (survives page reloads
+ *    without a loading flash)
+ * 2. If no stored user, call `checkAuth` → `fetchUserContext` → `setAccountId`
+ * 3. Subscribe to `supabase.auth.onAuthStateChange` for `SIGNED_IN`,
+ *    `TOKEN_REFRESHED`, and `SIGNED_OUT` events
+ *
+ * **Race-condition guards:**
+ * - `isLoggingIn` flag prevents `onAuthStateChange` from re-fetching context
+ *   while `login()` is already in progress
+ * - `SIGNED_IN` / `TOKEN_REFRESHED` handler skips re-fetch if user is already
+ *   loaded (prevents blocking page data fetches on browser focus)
+ * - `checkAuth` exits early if user is already loaded from `sessionStorage`
+ *
+ * **Account scope:** Calls `setAccountId(userContext.account_id)` after
+ * every successful context fetch, keeping `src/lib/api.ts` in sync.
+ *
+ * @seeAlso src/lib/supabase.ts (supabase client singleton)
+ * @seeAlso src/lib/api.ts (setAccountId, apiFetch)
+ * @seeAlso src/types/auth.ts (User shape)
+ * @seeAlso functions/auth.ts (backend `/api/auth?action=context` endpoint)
+ */
+
+import React, { createContext, useContext, useEffect, useState } from 'react'
+import { supabase } from '../lib/supabase'
+import { setAccountId, apiFetch } from '../lib/api'
+import { User } from '../types/auth'
+
+// ─── TYPES ───────────────────────────────────────────────────────────────────
+
+/**
+ * Shape of the value provided by `AuthContext`.
+ *
+ * @prop user - Resolved server-side user context, or null if unauthenticated
+ * @prop isLoading - True during initial `checkAuth` (prevents premature redirects)
+ * @prop login - Sign in with email/password and hydrate user context
+ * @prop logout - Sign out and clear user + account scope
+ * @prop refreshUser - Re-fetch user context from the server (e.g. after role change)
+ */
+interface AuthContextType {
+  user: User | null
+  isLoading: boolean
+  login: (email: string, password: string) => Promise<void>
+  logout: () => Promise<void>
+  refreshUser: () => Promise<void>
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined)
+
+// ─── useAuth ─────────────────────────────────────────────────────────────────
+
+/**
+ * Hook to access the authentication context. Must be called inside `AuthProvider`.
+ *
+ * @returns `AuthContextType` — user, isLoading, login, logout, refreshUser
+ * @throws Error('useAuth must be used within an AuthProvider') if called outside provider
+ * @sideEffects none (read-only context access)
+ * @calledBy every component that needs the current user or auth actions
+ */
+export function useAuth() {
+  const context = useContext(AuthContext)
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider')
+  }
+  return context
+}
+
+interface AuthProviderProps {
+  children: React.ReactNode
+}
+
+// ─── INTERNAL HELPERS ───────────────────────────────────────────────────────────
+
+/**
+ * Fetches the server-side user context from `GET /api/auth`. Returns null on
+ * any error (network, auth, or API) rather than throwing, so callers can
+ * apply fallback logic without try/catch.
+ *
+ * @returns Resolved `User` object or null on failure
+ * @throws never (all errors are caught internally)
+ * @sideEffects Network request via apiFetch; console logging
+ * @calledBy AuthProvider.login, AuthProvider.refreshUser, AuthProvider.checkAuth
+ */
+async function fetchUserContext(): Promise<User | null> {
+  try {
+    console.log('Fetching user context from backend API')
+
+    // Use backend API to get user context - backend handles all security
+    const response = await apiFetch('/api/auth', {
+      method: 'GET'
+    })
+
+    if (!response.ok) {
+      console.error('Backend API error:', response.status, response.statusText)
+      return null
+    }
+
+    const data = await response.json()
+    
+    if (data.error) {
+      console.error('Backend returned error:', data.error)
+      return null
+    }
+
+    if (!data.data) {
+      console.error('No user data returned from backend')
+      return null
+    }
+
+    console.log('User context loaded from backend:', {
+      id: data.data.id,
+      email: data.data.email,
+      account: data.data.account?.slug,
+      role: data.data.roles?.[0]
+    })
+
+    return data.data
+  } catch (error) {
+    console.error('Error fetching user context from backend:', error)
+    return null
+  }
+}
+
+// ─── AuthProvider ──────────────────────────────────────────────────────────────
+
+/**
+ * Root authentication provider. Wrap the entire application with this component
+ * to enable `useAuth()` in any descendant.
+ *
+ * @param children - React subtree to wrap
+ * @sideEffects
+ *   - Reads/writes `sessionStorage` key `spine_user` for persistence
+ *   - Calls `setAccountId` (mutates `src/lib/api.ts` module state)
+ *   - Subscribes to `supabase.auth.onAuthStateChange`; unsubscribes on unmount
+ * @calledBy src/main.tsx (app root)
+ *
+ * @example
+ * ```tsx
+ * <AuthProvider>
+ *   <App />
+ * </AuthProvider>
+ * ```
+ */
+export function AuthProvider({ children }: AuthProviderProps) {
+  // Initialize user from sessionStorage to survive full page reloads
+  const getStoredUser = (): User | null => {
+    try {
+      const stored = sessionStorage.getItem('spine_user')
+      return stored ? JSON.parse(stored) : null
+    } catch {
+      return null
+    }
+  }
+
+  const [user, setUser] = useState<User | null>(getStoredUser)
+  const [isLoading, setIsLoading] = useState(false) // Start with false, will set to true only if we need to check
+  const [isLoggingIn, setIsLoggingIn] = useState(false)
+
+  // Save user to sessionStorage whenever it changes
+  const setUserWithStorage = (user: User | null) => {
+    setUser(user)
+    try {
+      if (user) {
+        sessionStorage.setItem('spine_user', JSON.stringify(user))
+      } else {
+        sessionStorage.removeItem('spine_user')
+      }
+    } catch (error) {
+      console.warn('Failed to save user to sessionStorage:', error)
+    }
+  }
+
+  const login = async (email: string, password: string) => {
+    console.log('Login function called with:', email)
+    setIsLoggingIn(true)
+    
+    const { data, error } = await supabase.auth.signInWithPassword({
+      email,
+      password,
+    })
+
+    console.log('Supabase auth response:', { data, error })
+
+    if (error) {
+      console.error('Supabase auth error:', error)
+      setIsLoggingIn(false)
+      throw error
+    }
+
+    if (data.user) {
+      console.log('User logged in, fetching server context...')
+      
+      // Wait a moment for the session to be properly established
+      await new Promise(resolve => setTimeout(resolve, 100))
+      
+      // Fetch user context from server instead of hardcoding
+      const userContext = await fetchUserContext()
+      if (userContext) {
+        console.log('Setting server-derived user context:', userContext)
+        setUserWithStorage(userContext)
+        setAccountId(userContext.account_id)
+      } else {
+        console.error('Failed to get user context from server')
+        // Fallback to minimal user object
+        const fallbackUser = {
+          id: data.user.id,
+          email: data.user.email || '',
+          full_name: data.user.user_metadata?.full_name || data.user.email || 'User',
+          account_id: '',
+          roles: [],
+          permissions: [],
+        }
+        setUserWithStorage(fallbackUser)
+        setAccountId(fallbackUser.account_id)
+      }
+    }
+    
+    setIsLoggingIn(false)
+  }
+
+  const logout = async () => {
+    await supabase.auth.signOut()
+    setUserWithStorage(null)
+    setAccountId(null)
+  }
+
+  const refreshUser = async () => {
+    try {
+      console.log('Refreshing user...')
+      const { data: { session } } = await supabase.auth.getSession()
+      console.log('Got session:', session)
+      
+      if (!session?.user) {
+        console.log('No session user, setting user to null')
+        setUser(null)
+        return
+      }
+
+      // Fetch user context from server instead of hardcoding
+      const userContext = await fetchUserContext()
+      if (userContext) {
+        console.log('Setting server-derived user context:', userContext)
+        setUser(userContext)
+        setAccountId(userContext.account_id)
+      } else {
+        console.error('Failed to get user context from server')
+        setUser(null)
+        setAccountId(null)
+      }
+    } catch (error) {
+      console.error('Error refreshing user:', error)
+      setUser(null)
+      setAccountId(null)
+    }
+  }
+
+  useEffect(() => {
+    // Check initial auth state
+    const checkAuth = async () => {
+      try {
+        // Early exit if user is already loaded
+        if (user) {
+          console.log('User already loaded, skipping auth check:', user.id)
+          return
+        }
+        
+        // Only show loading if we actually need to check auth
+        setIsLoading(true)
+        console.log('Checking initial auth state...')
+        const { data: { session } } = await supabase.auth.getSession()
+        console.log('Initial session check:', session?.user?.id ? 'User found' : 'No user')
+        
+        if (session?.user) {
+          // Fetch user context from server instead of hardcoding
+          const userContext = await fetchUserContext()
+          if (userContext) {
+            console.log('Setting server-derived user context from session:', userContext)
+            setUserWithStorage(userContext)
+            setAccountId(userContext.account_id)
+          } else {
+            console.error('Failed to get user context from server')
+            setUserWithStorage(null)
+            setAccountId(null)
+          }
+        }
+      } catch (error) {
+        console.error('Auth check failed:', error)
+        setUserWithStorage(null)
+        setAccountId(null)
+      } finally {
+        // Always set loading to false after checking
+        setIsLoading(false)
+        console.log('Auth check completed, loading set to false')
+      }
+    }
+
+    checkAuth()
+
+    // Listen for auth changes
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(
+      async (event, session) => {
+        console.log('Auth state changed:', event, session?.user?.id)
+        
+        // Don't refresh during login to avoid conflicts
+        if (isLoggingIn) {
+          console.log('Skipping refresh during login')
+          return
+        }
+        
+        if (event === 'SIGNED_IN' || event === 'TOKEN_REFRESHED') {
+          if (session?.user) {
+            // Skip re-fetching if user is already loaded — prevents blocking
+            // page fetches when Supabase re-fires SIGNED_IN on browser focus
+            setUser(currentUser => {
+              if (currentUser) {
+                console.log('Auth state changed: user already loaded, skipping re-fetch')
+                return currentUser
+              }
+              // No user yet — fetch context asynchronously
+              fetchUserContext().then(userContext => {
+                if (userContext) {
+                  console.log('Setting server-derived user context from auth state change:', userContext)
+                  setUserWithStorage(userContext)
+                  setAccountId(userContext.account_id)
+                } else {
+                  console.error('Failed to get user context from server')
+                  setUserWithStorage(null)
+                  setAccountId(null)
+                }
+              })
+              return currentUser
+            })
+          }
+        } else if (event === 'SIGNED_OUT') {
+          setUserWithStorage(null)
+          setAccountId(null)
+        }
+      }
+    )
+
+    return () => subscription.unsubscribe()
+  }, [isLoggingIn])
+
+  const value = {
+    user,
+    isLoading,
+    login,
+    logout,
+    refreshUser
+  }
+
+  // Debug: Log loading state changes
+  console.log('AuthContext state:', { user: user?.id, isLoading, userEmail: user?.email })
+
+  return (
+    <AuthContext.Provider value={value}>
+      {children}
+    </AuthContext.Provider>
+  )
+}

package/.framework/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}