insforge 0.3.1

package/frontend/src/lib/contexts/OnboardStepContext.tsx

@@ -0,0 +1,68 @@
+import React, { createContext, useContext, useState, useEffect } from 'react';
+import { OnboardStep, TOTAL_STEPS } from '@/features/onboard/types';
+
+interface OnboardContextValue {
+  currentStep: OnboardStep;
+  updateStep: (step: OnboardStep) => void;
+  getCurrentDescription: () => string;
+  totalSteps: number;
+}
+
+const ONBOARD_STORAGE_KEY = 'insforge_onboard_step';
+export const STEP_DESCRIPTIONS = [
+  'Install Node.js',
+  'Install InsForge',
+  'Test the Connection',
+  'Start Using InsForge',
+] as const;
+
+const OnboardContext = createContext<OnboardContextValue | null>(null);
+
+export function OnboardStepProvider({ children }: { children: React.ReactNode }) {
+  const [currentStep, setCurrentStep] = useState<OnboardStep>(() => {
+    const saved = localStorage.getItem(ONBOARD_STORAGE_KEY);
+    const n = saved ? parseInt(saved, 10) : NaN;
+    return n >= OnboardStep.INSTALL_NODEJS && n <= OnboardStep.FINAL_SETUP
+      ? (n as OnboardStep)
+      : OnboardStep.INSTALL_NODEJS;
+  });
+
+  useEffect(() => {
+    const onStorage = (e: StorageEvent) => {
+      if (e.key === ONBOARD_STORAGE_KEY && e.newValue) {
+        const n = parseInt(e.newValue, 10) as OnboardStep;
+        if (n >= OnboardStep.INSTALL_NODEJS && n <= OnboardStep.FINAL_SETUP) {
+          setCurrentStep(n);
+        }
+      }
+    };
+    window.addEventListener('storage', onStorage);
+    return () => window.removeEventListener('storage', onStorage);
+  }, []);
+
+  const updateStep = (step: OnboardStep) => {
+    if (step < OnboardStep.INSTALL_NODEJS || step > OnboardStep.FINAL_SETUP) {
+      return;
+    }
+    setCurrentStep(step);
+    localStorage.setItem(ONBOARD_STORAGE_KEY, step.toString());
+  };
+
+  const getCurrentDescription = () => STEP_DESCRIPTIONS[currentStep - 1];
+
+  return (
+    <OnboardContext.Provider
+      value={{ currentStep, updateStep, getCurrentDescription, totalSteps: TOTAL_STEPS }}
+    >
+      {children}
+    </OnboardContext.Provider>
+  );
+}
+
+export function useOnboardStep() {
+  const ctx = useContext(OnboardContext);
+  if (!ctx) {
+    throw new Error('useOnboardStep must be used within an OnboardProvider');
+  }
+  return ctx;
+}

package/frontend/src/lib/contexts/SocketContext.tsx

@@ -0,0 +1,303 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useCallback,
+  ReactNode,
+  useMemo,
+} from 'react';
+import { io, Socket } from 'socket.io-client';
+import { apiClient } from '@/lib/api/client';
+import { useAuth } from '@/lib/contexts/AuthContext';
+
+// ============================================================================
+// Types & Enums
+// ============================================================================
+
+/**
+ * Server-to-client event types
+ */
+export enum ServerEvents {
+  NOTIFICATION = 'notification',
+  DATA_UPDATE = 'data:update',
+  MCP_CONNECTED = 'mcp:connected',
+}
+
+/**
+ * Client-to-server event types
+ */
+export enum ClientEvents {
+  SUBSCRIBE = 'subscribe',
+  UNSUBSCRIBE = 'unsubscribe',
+}
+
+/**
+ * Base message structure for all socket communications
+ */
+export interface SocketMessage<T = unknown> {
+  type: string;
+  payload?: T;
+  timestamp: number;
+  id?: string;
+}
+
+// ============================================================================
+// Payload Types
+// ============================================================================
+
+export interface NotificationPayload {
+  level: 'info' | 'warning' | 'error' | 'success';
+  title: string;
+  message: string;
+}
+
+export enum DataUpdateResourceType {
+  METADATA = 'metadata',
+  DATABASE_SCHEMA = 'database_schema',
+  TABLE_SCHEMA = 'table_schema',
+  STORAGE_SCHEMA = 'storage_schema',
+  BUCKET_SCHEMA = 'bucket_schema',
+  OAUTH_SCHEMA = 'oauth_schmea',
+}
+
+export interface DataUpdatePayload {
+  resource: DataUpdateResourceType;
+  action: 'created' | 'updated' | 'deleted';
+  data: unknown;
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+interface SocketState {
+  isConnected: boolean;
+  connectionError: string | null;
+  socketId: string | null;
+}
+
+interface SocketActions {
+  connect: (token: string | null) => void;
+  disconnect: () => void;
+  subscribe: (channel: string, filters?: Record<string, unknown>) => void;
+  unsubscribe: (channel: string) => void;
+  emit: (event: ClientEvents, data?: unknown) => void;
+}
+
+interface SocketContextValue extends SocketState, SocketActions {
+  socket: Socket | null;
+}
+
+// ============================================================================
+// Context & Provider
+// ============================================================================
+
+const SocketContext = createContext<SocketContextValue | null>(null);
+
+interface SocketProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Socket.IO Provider - Manages WebSocket connection for the entire application
+ */
+export function SocketProvider({ children }: SocketProviderProps) {
+  // Get authentication state
+  const { isAuthenticated } = useAuth();
+  // State
+  const [state, setState] = useState<SocketState>({
+    isConnected: false,
+    connectionError: null,
+    socketId: null,
+  });
+
+  // Refs
+  const socketRef = useRef<Socket | null>(null);
+  const subscriptionsRef = useRef<Set<string>>(new Set());
+
+  /**
+   * Update state helper
+   */
+  const updateState = useCallback((updates: Partial<SocketState>) => {
+    setState((prev) => ({ ...prev, ...updates }));
+  }, []);
+
+  /**
+   * Create and configure socket connection
+   */
+  const createSocket = useCallback(
+    (token: string): Socket => {
+      const socket = io('/', {
+        auth: {
+          token,
+        },
+      });
+
+      // Core connection events
+      socket.on('connect', () => {
+        updateState({
+          isConnected: true,
+          connectionError: null,
+          socketId: socket.id || null,
+        });
+      });
+
+      socket.on('disconnect', (reason) => {
+        updateState({
+          isConnected: false,
+          socketId: null,
+          connectionError: `Disconnected: ${reason}`,
+        });
+      });
+
+      socket.on('connect_error', (error) => {
+        updateState({
+          connectionError: `Connection failed: ${error.message}`,
+          isConnected: false,
+        });
+      });
+
+      socket.on('error', (error) => {
+        updateState({ connectionError: error?.message || 'Unknown error' });
+      });
+
+      socket.on('reconnect', () => {
+        updateState({
+          isConnected: true,
+          connectionError: null,
+        });
+
+        // Re-subscribe to channels after reconnection
+        subscriptionsRef.current.forEach((channel) => {
+          socket.emit(ClientEvents.SUBSCRIBE, { channel });
+        });
+      });
+
+      return socket;
+    },
+    [updateState]
+  );
+
+  /**
+   * Connect to socket server
+   */
+  const connect = useCallback(
+    (token: string | null) => {
+      // Don't connect without a token
+      if (!token) {
+        return;
+      }
+
+      // Don't reconnect if already connected with the same token
+      if (socketRef.current?.connected) {
+        return;
+      }
+
+      try {
+        const socket = createSocket(token);
+        socketRef.current = socket;
+      } catch (error) {
+        console.error('Socket connection error:', error);
+        updateState({ connectionError: 'Failed to establish connection' });
+      }
+    },
+    [createSocket, updateState]
+  );
+
+  /**
+   * Disconnect from socket server
+   */
+  const disconnect = useCallback(() => {
+    if (socketRef.current) {
+      socketRef.current.disconnect();
+      socketRef.current = null;
+    }
+
+    updateState({
+      isConnected: false,
+      connectionError: null,
+      socketId: null,
+    });
+
+    subscriptionsRef.current.clear();
+  }, [updateState]);
+
+  /**
+   * Subscribe to a channel
+   */
+  const subscribe = useCallback((channel: string, filters?: Record<string, unknown>) => {
+    if (!socketRef.current?.connected) {
+      return;
+    }
+
+    socketRef.current.emit(ClientEvents.SUBSCRIBE, { channel, filters });
+    subscriptionsRef.current.add(channel);
+  }, []);
+
+  /**
+   * Unsubscribe from a channel
+   */
+  const unsubscribe = useCallback((channel: string) => {
+    if (!socketRef.current?.connected) {
+      return;
+    }
+
+    socketRef.current.emit(ClientEvents.UNSUBSCRIBE, { channel });
+    subscriptionsRef.current.delete(channel);
+  }, []);
+
+  /**
+   * Emit event to server
+   */
+  const emit = useCallback((event: ClientEvents, data?: unknown) => {
+    socketRef.current?.emit(event, data);
+  }, []);
+
+  // Monitor authentication state and token changes
+  useEffect(() => {
+    const token = apiClient.getToken();
+
+    if (isAuthenticated && token) {
+      // Connect when authenticated with a valid token
+      connect(token);
+    } else {
+      // Disconnect when not authenticated or no token
+      disconnect();
+    }
+  }, [isAuthenticated, connect, disconnect]);
+
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      disconnect();
+    };
+  }, [disconnect]);
+
+  // Context value
+  const contextValue = useMemo<SocketContextValue>(
+    () => ({
+      // State
+      socket: socketRef.current,
+      ...state,
+      // Actions
+      connect,
+      disconnect,
+      subscribe,
+      unsubscribe,
+      emit,
+    }),
+    [state, connect, disconnect, subscribe, unsubscribe, emit]
+  );
+
+  return <SocketContext.Provider value={contextValue}>{children}</SocketContext.Provider>;
+}
+
+export function useSocket() {
+  const context = useContext(SocketContext);
+  if (!context) {
+    throw new Error('useSocketContext must be used within a SocketProvider');
+  }
+  return context;
+}

package/frontend/src/lib/contexts/ThemeContext.tsx

@@ -0,0 +1,125 @@
+import React, { createContext, useContext, useEffect, useState } from 'react';
+
+type Theme = 'light' | 'dark' | 'system';
+type ResolvedTheme = 'light' | 'dark';
+
+interface ThemeContextType {
+  theme: Theme;
+  resolvedTheme: ResolvedTheme;
+  setTheme: (theme: Theme) => void;
+  toggleTheme: () => void;
+}
+
+const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+
+const STORAGE_KEY = 'insforge-theme';
+
+function getSystemTheme(): ResolvedTheme {
+  if (typeof window === 'undefined') {
+    return 'light';
+  }
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+function resolveTheme(theme: Theme): ResolvedTheme {
+  if (theme === 'system') {
+    return getSystemTheme();
+  }
+  return theme;
+}
+
+interface ThemeProviderProps {
+  children: React.ReactNode;
+  forcedTheme?: ResolvedTheme;
+  storageKey?: string;
+}
+
+export function ThemeProvider({
+  children,
+  forcedTheme,
+  storageKey = STORAGE_KEY,
+}: ThemeProviderProps) {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (forcedTheme) {
+      return forcedTheme;
+    }
+
+    if (typeof window !== 'undefined') {
+      const stored = localStorage.getItem(storageKey);
+      if (stored === 'light' || stored === 'dark' || stored === 'system') {
+        return stored;
+      }
+    }
+    return 'system';
+  });
+
+  const resolvedTheme = forcedTheme || resolveTheme(theme);
+
+  useEffect(() => {
+    const root = window.document.documentElement;
+
+    // Remove both classes first
+    root.classList.remove('light', 'dark');
+
+    // Add the resolved theme class
+    root.classList.add(resolvedTheme);
+
+    // Update meta theme-color for mobile browsers
+    const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+    if (metaThemeColor) {
+      metaThemeColor.setAttribute('content', resolvedTheme === 'dark' ? '#0a0a0a' : '#ffffff');
+    }
+  }, [resolvedTheme]);
+
+  useEffect(() => {
+    if (forcedTheme) {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+    const handleChange = () => {
+      if (theme === 'system') {
+        const root = window.document.documentElement;
+        const newResolvedTheme = getSystemTheme();
+        root.classList.remove('light', 'dark');
+        root.classList.add(newResolvedTheme);
+      }
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, [theme, forcedTheme]);
+
+  const setTheme = (newTheme: Theme) => {
+    if (forcedTheme) {
+      return;
+    }
+
+    setThemeState(newTheme);
+    localStorage.setItem(storageKey, newTheme);
+  };
+
+  const toggleTheme = () => {
+    if (forcedTheme) {
+      return;
+    }
+
+    const newTheme = resolvedTheme === 'light' ? 'dark' : 'light';
+    setTheme(newTheme);
+  };
+
+  return (
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme, toggleTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}

package/frontend/src/lib/hooks/useAuth.ts

@@ -0,0 +1,4 @@
+// Re-export the useAuth hook from AuthContext for backwards compatibility
+export { useAuth } from '@/lib/contexts/AuthContext';
+
+// Additional auth-related hooks can be added here if needed

package/frontend/src/lib/hooks/useConfirm.ts

@@ -0,0 +1,55 @@
+import { useState } from 'react';
+
+interface ConfirmOptions {
+  title: string;
+  description: string;
+  confirmText?: string;
+  cancelText?: string;
+  destructive?: boolean;
+}
+
+export function useConfirm() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [options, setOptions] = useState<ConfirmOptions>({
+    title: '',
+    description: '',
+  });
+  const [resolvePromise, setResolvePromise] = useState<((value: boolean) => void) | null>(null);
+
+  const confirm = (confirmOptions: ConfirmOptions): Promise<boolean> => {
+    setOptions(confirmOptions);
+    setIsOpen(true);
+
+    return new Promise<boolean>((resolve) => {
+      setResolvePromise(() => resolve);
+    });
+  };
+
+  const handleConfirm = () => {
+    resolvePromise?.(true);
+    setIsOpen(false);
+  };
+
+  const handleCancel = () => {
+    resolvePromise?.(false);
+    setIsOpen(false);
+  };
+
+  return {
+    confirm,
+    confirmDialogProps: {
+      open: isOpen,
+      onOpenChange: (open: boolean) => {
+        if (!open) {
+          handleCancel();
+        }
+      },
+      title: options.title,
+      description: options.description,
+      confirmText: options.confirmText,
+      cancelText: options.cancelText,
+      destructive: options.destructive,
+      onConfirm: handleConfirm,
+    },
+  };
+}

package/frontend/src/lib/hooks/useInterval.ts

@@ -0,0 +1,27 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+export function useInterval(callback: () => void, delay: number | null) {
+  const savedCallback = useRef(callback);
+
+  // Remember the latest callback if it changes.
+  useLayoutEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+
+  // Set up the interval.
+  useEffect(() => {
+    // Don't schedule if no delay is specified.
+    // Note: 0 is a valid value for delay.
+    if (delay === null) {
+      return;
+    }
+
+    const id = setInterval(() => {
+      savedCallback.current();
+    }, delay);
+
+    return () => {
+      clearInterval(id);
+    };
+  }, [delay]);
+}

package/frontend/src/lib/hooks/useMediaQuery.ts

@@ -0,0 +1,59 @@
+import { useCallback, useLayoutEffect, useState } from 'react';
+
+type UseMediaQueryOptions = {
+  defaultValue?: boolean;
+  initializeWithValue?: boolean;
+};
+
+const IS_SERVER = typeof window === 'undefined';
+
+export function useMediaQuery(
+  query: string,
+  { defaultValue = false, initializeWithValue = true }: UseMediaQueryOptions = {}
+): boolean {
+  const getMatches = useCallback(
+    (query: string): boolean => {
+      if (IS_SERVER) {
+        return defaultValue;
+      }
+      return window.matchMedia(query).matches;
+    },
+    [defaultValue]
+  );
+
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (initializeWithValue) {
+      return getMatches(query);
+    }
+    return defaultValue;
+  });
+
+  // Handles the change event of the media query.
+  const handleChange = useCallback(() => {
+    setMatches(getMatches(query));
+  }, [getMatches, query]);
+
+  useLayoutEffect(() => {
+    const matchMedia = window.matchMedia(query);
+
+    // Triggered at the first client-side load and if query changes
+    handleChange();
+
+    // Use deprecated `addListener` and `removeListener` to support Safari < 14
+    if (matchMedia.addListener) {
+      matchMedia.addListener(handleChange);
+    } else {
+      matchMedia.addEventListener('change', handleChange);
+    }
+
+    return () => {
+      if (matchMedia.removeListener) {
+        matchMedia.removeListener(handleChange);
+      } else {
+        matchMedia.removeEventListener('change', handleChange);
+      }
+    };
+  }, [handleChange, query]);
+
+  return matches;
+}

package/frontend/src/lib/hooks/useOnboardingCompletion.ts

@@ -0,0 +1,29 @@
+import { useMemo } from 'react';
+
+const ONBOARDING_COMPLETION_KEY = 'insforge_onboarding_completed';
+
+export function useOnboardingCompletion() {
+  const isCompleted = useMemo<boolean>(() => {
+    const stored = localStorage.getItem(ONBOARDING_COMPLETION_KEY);
+    return stored === 'true';
+  }, []);
+
+  const markAsCompleted = () => {
+    localStorage.setItem(ONBOARDING_COMPLETION_KEY, 'true');
+  };
+
+  const resetCompletion = () => {
+    localStorage.setItem(ONBOARDING_COMPLETION_KEY, 'false');
+  };
+
+  return {
+    isCompleted,
+    markAsCompleted,
+    resetCompletion,
+  };
+}
+
+// Export utility function for direct usage
+export const markOnboardingAsCompleted = () => {
+  localStorage.setItem(ONBOARDING_COMPLETION_KEY, 'true');
+};

package/frontend/src/lib/hooks/usePagination.ts

@@ -0,0 +1,27 @@
+import { useState, useMemo } from 'react';
+
+export function usePagination<T>(data: T[], defaultPageSize = 50) {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [pageSize] = useState(defaultPageSize);
+
+  const paginatedData = useMemo(() => {
+    const startIndex = (currentPage - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    return data.slice(startIndex, endIndex);
+  }, [data, currentPage, pageSize]);
+
+  const totalPages = Math.ceil(data.length / pageSize);
+  const startRecord = (currentPage - 1) * pageSize + 1;
+  const endRecord = Math.min(currentPage * pageSize, data.length);
+
+  return {
+    currentPage,
+    setCurrentPage,
+    pageSize,
+    paginatedData,
+    totalPages,
+    startRecord,
+    endRecord,
+    totalRecords: data.length,
+  };
+}