create-fluxstack 1.13.0 → 1.14.0

package/core/client/hooks/useLiveDebugger.ts

@@ -0,0 +1,392 @@
+// 🔍 FluxStack Live Component Debugger - Client Hook
+//
+// Connects to the debug WebSocket endpoint and streams debug events.
+// Provides reactive state for building debugger UIs.
+//
+// Usage:
+//   const debugger = useLiveDebugger()
+//   debugger.components   // Active components with current states
+//   debugger.events       // Event timeline
+//   debugger.connected    // Connection status
+
+import { useState, useEffect, useRef, useCallback } from 'react'
+
+// ===== Types (mirrored from server) =====
+
+export type DebugEventType =
+  | 'COMPONENT_MOUNT'
+  | 'COMPONENT_UNMOUNT'
+  | 'COMPONENT_REHYDRATE'
+  | 'STATE_CHANGE'
+  | 'ACTION_CALL'
+  | 'ACTION_RESULT'
+  | 'ACTION_ERROR'
+  | 'ROOM_JOIN'
+  | 'ROOM_LEAVE'
+  | 'ROOM_EMIT'
+  | 'ROOM_EVENT_RECEIVED'
+  | 'WS_CONNECT'
+  | 'WS_DISCONNECT'
+  | 'ERROR'
+
+export interface DebugEvent {
+  id: string
+  timestamp: number
+  type: DebugEventType
+  componentId: string | null
+  componentName: string | null
+  data: Record<string, unknown>
+}
+
+export interface ComponentSnapshot {
+  componentId: string
+  componentName: string
+  /** Developer-defined label for easier identification in the debugger */
+  debugLabel?: string
+  state: Record<string, unknown>
+  rooms: string[]
+  mountedAt: number
+  lastActivity: number
+  actionCount: number
+  stateChangeCount: number
+  errorCount: number
+}
+
+export interface DebugSnapshot {
+  components: ComponentSnapshot[]
+  connections: number
+  uptime: number
+  totalEvents: number
+}
+
+export interface DebugFilter {
+  componentId?: string | null
+  types?: Set<DebugEventType>
+  search?: string
+}
+
+export interface UseLiveDebuggerReturn {
+  // Connection
+  connected: boolean
+  connecting: boolean
+  /** Server reported that debugging is disabled */
+  serverDisabled: boolean
+
+  // Data
+  components: ComponentSnapshot[]
+  events: DebugEvent[]
+  filteredEvents: DebugEvent[]
+  snapshot: DebugSnapshot | null
+
+  // Selected component
+  selectedComponentId: string | null
+  selectedComponent: ComponentSnapshot | null
+  selectComponent: (id: string | null) => void
+
+  // Filtering
+  filter: DebugFilter
+  setFilter: (filter: Partial<DebugFilter>) => void
+
+  // Controls
+  paused: boolean
+  togglePause: () => void
+  clearEvents: () => void
+  reconnect: () => void
+
+  // Stats
+  eventCount: number
+  componentCount: number
+}
+
+export interface UseLiveDebuggerOptions {
+  /** Max events to keep in memory. Default: 500 */
+  maxEvents?: number
+  /** Auto-connect on mount. Default: true */
+  autoConnect?: boolean
+  /** Custom WebSocket URL */
+  url?: string
+}
+
+// ===== Hook =====
+
+export function useLiveDebugger(options: UseLiveDebuggerOptions = {}): UseLiveDebuggerReturn {
+  const {
+    maxEvents = 500,
+    autoConnect = true,
+    url
+  } = options
+
+  // State
+  const [connected, setConnected] = useState(false)
+  const [connecting, setConnecting] = useState(false)
+  const [components, setComponents] = useState<ComponentSnapshot[]>([])
+  const [events, setEvents] = useState<DebugEvent[]>([])
+  const [snapshot, setSnapshot] = useState<DebugSnapshot | null>(null)
+  const [selectedComponentId, setSelectedComponentId] = useState<string | null>(null)
+  const [filter, setFilterState] = useState<DebugFilter>({})
+  const [paused, setPaused] = useState(false)
+  const [serverDisabled, setServerDisabled] = useState(false)
+
+  // Refs
+  const wsRef = useRef<WebSocket | null>(null)
+  const pausedRef = useRef(false)
+  const serverDisabledRef = useRef(false)
+  const reconnectTimeoutRef = useRef<number | null>(null)
+
+  // Keep refs in sync
+  pausedRef.current = paused
+  serverDisabledRef.current = serverDisabled
+
+  // Build WebSocket URL
+  const getWsUrl = useCallback(() => {
+    if (url) return url
+    if (typeof window === 'undefined') return 'ws://localhost:3000/api/live/debug/ws'
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+    return `${protocol}//${window.location.host}/api/live/debug/ws`
+  }, [url])
+
+  // Connect
+  const connect = useCallback(() => {
+    if (wsRef.current?.readyState === WebSocket.CONNECTING) return
+    if (wsRef.current?.readyState === WebSocket.OPEN) return
+
+    setConnecting(true)
+
+    try {
+      const ws = new WebSocket(getWsUrl())
+      wsRef.current = ws
+
+      ws.onopen = () => {
+        setConnected(true)
+        setConnecting(false)
+      }
+
+      ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data)
+
+          if (msg.type === 'DEBUG_DISABLED') {
+            // Server has debugging disabled — stop reconnecting
+            setServerDisabled(true)
+            return
+          }
+
+          if (msg.type === 'DEBUG_WELCOME') {
+            // Initial snapshot
+            setServerDisabled(false)
+            const snap = msg.snapshot as DebugSnapshot
+            setSnapshot(snap)
+            setComponents(snap.components)
+          } else if (msg.type === 'DEBUG_EVENT') {
+            if (pausedRef.current) return
+
+            const debugEvent = msg.event as DebugEvent
+
+            // Update events list
+            setEvents(prev => {
+              const next = [...prev, debugEvent]
+              return next.length > maxEvents ? next.slice(-maxEvents) : next
+            })
+
+            // Update component snapshots based on event
+            updateComponentsFromEvent(debugEvent)
+          } else if (msg.type === 'DEBUG_SNAPSHOT') {
+            const snap = msg.snapshot as DebugSnapshot
+            setSnapshot(snap)
+            setComponents(snap.components)
+          }
+        } catch {
+          // Ignore parse errors
+        }
+      }
+
+      ws.onclose = () => {
+        setConnected(false)
+        setConnecting(false)
+        wsRef.current = null
+
+        // Don't reconnect if server told us debug is disabled
+        if (serverDisabledRef.current) return
+
+        // Auto-reconnect after 3 seconds
+        reconnectTimeoutRef.current = window.setTimeout(() => {
+          if (autoConnect) connect()
+        }, 3000)
+      }
+
+      ws.onerror = () => {
+        setConnecting(false)
+      }
+    } catch {
+      setConnecting(false)
+    }
+  }, [getWsUrl, maxEvents, autoConnect])
+
+  // Update components from incoming events
+  const updateComponentsFromEvent = useCallback((event: DebugEvent) => {
+    setComponents(prev => {
+      switch (event.type) {
+        case 'COMPONENT_MOUNT': {
+          if (!event.componentId || !event.componentName) return prev
+          const existing = prev.find(c => c.componentId === event.componentId)
+          if (existing) return prev
+          return [...prev, {
+            componentId: event.componentId,
+            componentName: event.componentName,
+            debugLabel: (event.data.debugLabel as string) || undefined,
+            state: (event.data.initialState as Record<string, unknown>) || {},
+            rooms: event.data.room ? [event.data.room as string] : [],
+            mountedAt: event.timestamp,
+            lastActivity: event.timestamp,
+            actionCount: 0,
+            stateChangeCount: 0,
+            errorCount: 0
+          }]
+        }
+
+        case 'COMPONENT_UNMOUNT': {
+          return prev.filter(c => c.componentId !== event.componentId)
+        }
+
+        case 'STATE_CHANGE': {
+          return prev.map(c => {
+            if (c.componentId !== event.componentId) return c
+            return {
+              ...c,
+              state: (event.data.fullState as Record<string, unknown>) || c.state,
+              stateChangeCount: c.stateChangeCount + 1,
+              lastActivity: event.timestamp
+            }
+          })
+        }
+
+        case 'ACTION_CALL': {
+          return prev.map(c => {
+            if (c.componentId !== event.componentId) return c
+            return {
+              ...c,
+              actionCount: c.actionCount + 1,
+              lastActivity: event.timestamp
+            }
+          })
+        }
+
+        case 'ACTION_ERROR':
+        case 'ERROR': {
+          return prev.map(c => {
+            if (c.componentId !== event.componentId) return c
+            return {
+              ...c,
+              errorCount: c.errorCount + 1,
+              lastActivity: event.timestamp
+            }
+          })
+        }
+
+        case 'ROOM_JOIN': {
+          return prev.map(c => {
+            if (c.componentId !== event.componentId) return c
+            const roomId = event.data.roomId as string
+            if (c.rooms.includes(roomId)) return c
+            return { ...c, rooms: [...c.rooms, roomId] }
+          })
+        }
+
+        case 'ROOM_LEAVE': {
+          return prev.map(c => {
+            if (c.componentId !== event.componentId) return c
+            const roomId = event.data.roomId as string
+            return { ...c, rooms: c.rooms.filter(r => r !== roomId) }
+          })
+        }
+
+        default:
+          return prev.map(c => {
+            if (c.componentId !== event.componentId) return c
+            return { ...c, lastActivity: event.timestamp }
+          })
+      }
+    })
+  }, [])
+
+  // Disconnect
+  const disconnect = useCallback(() => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+    if (wsRef.current) {
+      wsRef.current.close()
+      wsRef.current = null
+    }
+    setConnected(false)
+    setConnecting(false)
+  }, [])
+
+  // Reconnect
+  const reconnect = useCallback(() => {
+    disconnect()
+    setTimeout(() => connect(), 100)
+  }, [connect, disconnect])
+
+  // Filter events
+  const filteredEvents = events.filter(event => {
+    if (filter.componentId && event.componentId !== filter.componentId) return false
+    if (filter.types && filter.types.size > 0 && !filter.types.has(event.type)) return false
+    if (filter.search) {
+      const search = filter.search.toLowerCase()
+      const matchesData = JSON.stringify(event.data).toLowerCase().includes(search)
+      const matchesName = event.componentName?.toLowerCase().includes(search)
+      const matchesType = event.type.toLowerCase().includes(search)
+      if (!matchesData && !matchesName && !matchesType) return false
+    }
+    return true
+  })
+
+  // Selected component
+  const selectedComponent = selectedComponentId
+    ? components.find(c => c.componentId === selectedComponentId) ?? null
+    : null
+
+  // Filter setter
+  const setFilter = useCallback((partial: Partial<DebugFilter>) => {
+    setFilterState(prev => ({ ...prev, ...partial }))
+  }, [])
+
+  // Toggle pause
+  const togglePause = useCallback(() => {
+    setPaused(prev => !prev)
+  }, [])
+
+  // Clear events
+  const clearEvents = useCallback(() => {
+    setEvents([])
+  }, [])
+
+  // Auto-connect
+  useEffect(() => {
+    if (autoConnect) connect()
+    return () => disconnect()
+  }, [autoConnect, connect, disconnect])
+
+  return {
+    connected,
+    connecting,
+    serverDisabled,
+    components,
+    events,
+    filteredEvents,
+    snapshot,
+    selectedComponentId,
+    selectedComponent,
+    selectComponent: setSelectedComponentId,
+    filter,
+    setFilter,
+    paused,
+    togglePause,
+    clearEvents,
+    reconnect,
+    eventCount: events.length,
+    componentCount: components.length
+  }
+}

package/core/client/index.ts

@@ -29,3 +29,17 @@ export { useLiveUpload } from './hooks/useLiveUpload'
 
 // Live Component Hook (API principal)
 export { Live } from './components/Live'
+
+// Live Component Debugger
+export { LiveDebugger } from './components/LiveDebugger'
+export type { LiveDebuggerProps } from './components/LiveDebugger'
+export { useLiveDebugger } from './hooks/useLiveDebugger'
+export type {
+  DebugEvent,
+  DebugEventType,
+  ComponentSnapshot,
+  DebugSnapshot,
+  DebugFilter,
+  UseLiveDebuggerReturn,
+  UseLiveDebuggerOptions
+} from './hooks/useLiveDebugger'

package/core/plugins/built-in/index.ts

@@ -1,135 +1,135 @@
-/**
- * Built-in Plugins for FluxStack
- * Core plugins that provide essential functionality
- *
- * Note: Logger is NOT a plugin - it's core infrastructure used by plugins
- */
-
-// Import all built-in plugins
-import { swaggerPlugin } from './swagger'
-import { vitePlugin } from './vite'
-import { monitoringPlugin } from './monitoring'
-
-// Export individual plugins
-export { swaggerPlugin } from './swagger'
-export { vitePlugin } from './vite'
-export { monitoringPlugin } from './monitoring'
-
-// Deprecated: staticPlugin is now merged into vitePlugin (auto-detects dev/prod)
-/** @deprecated Use vitePlugin instead - it now handles both dev and prod */
-export const staticPlugin = vitePlugin
-
-// Export as a collection
-export const builtInPlugins = {
-  swagger: swaggerPlugin,
-  vite: vitePlugin,
-  static: staticPlugin,
-  monitoring: monitoringPlugin
-} as const
-
-// Export as an array for easy registration
-export const builtInPluginsList = [
-  swaggerPlugin,
-  vitePlugin,
-  staticPlugin,
-  monitoringPlugin
-] as const
-
-// Plugin categories
-export const pluginCategories = {
-  core: [vitePlugin], // vitePlugin now handles both dev (Vite) and prod (static)
-  development: [vitePlugin],
-  documentation: [swaggerPlugin],
-  monitoring: [monitoringPlugin]
-} as const
-
-// Default plugin configuration
-export const defaultPluginConfig = {
-  swagger: {
-    enabled: true,
-    path: '/swagger',
-    title: 'FluxStack API',
-    description: 'Modern full-stack TypeScript framework with type-safe API endpoints'
-  },
-  vite: {
-    enabled: true,
-    port: 5173,
-    host: 'localhost',
-    checkInterval: 2000,
-    maxRetries: 10,
-    timeout: 5000
-  },
-  static: {
-    enabled: true,
-    publicDir: 'public',
-    distDir: 'dist/client',
-    indexFile: 'index.html',
-    spa: {
-      enabled: true,
-      fallback: 'index.html'
-    }
-  },
-  monitoring: {
-    enabled: false, // Disabled by default to avoid overhead
-    httpMetrics: true,
-    systemMetrics: true,
-    customMetrics: true,
-    collectInterval: 5000,
-    retentionPeriod: 300000,
-    exporters: [
-      {
-        type: 'console',
-        interval: 30000,
-        enabled: false
-      }
-    ],
-    thresholds: {
-      responseTime: 1000,
-      errorRate: 0.05,
-      memoryUsage: 0.8,
-      cpuUsage: 0.8
-    }
-  }
-} as const
-
-/**
- * Get default plugins for a specific environment
- */
-export function getDefaultPlugins(environment: 'development' | 'production' | 'test' = 'development') {
-  // vitePlugin now auto-detects dev/prod and serves appropriately
-  const basePlugins = [vitePlugin]
-
-  switch (environment) {
-    case 'development':
-      return [...basePlugins, swaggerPlugin, monitoringPlugin]
-    case 'production':
-      return [...basePlugins, monitoringPlugin]
-    case 'test':
-      return [] // Minimal plugins for testing
-    default:
-      return basePlugins
-  }
-}
-
-/**
- * Get plugin by name
- */
-export function getBuiltInPlugin(name: string) {
-  return builtInPlugins[name as keyof typeof builtInPlugins]
-}
-
-/**
- * Check if a plugin is built-in
- */
-export function isBuiltInPlugin(name: string): boolean {
-  return name in builtInPlugins
-}
-
-/**
- * Get plugins by category
- */
-export function getPluginsByCategory(category: keyof typeof pluginCategories) {
-  return pluginCategories[category] || []
-}
-
+/**
+ * Built-in Plugins for FluxStack
+ * Core plugins that provide essential functionality
+ *
+ * Note: Logger is NOT a plugin - it's core infrastructure used by plugins
+ */
+
+// Import all built-in plugins
+import { swaggerPlugin } from './swagger'
+import { vitePlugin } from './vite'
+import { monitoringPlugin } from './monitoring'
+
+// Export individual plugins
+export { swaggerPlugin } from './swagger'
+export { vitePlugin } from './vite'
+export { monitoringPlugin } from './monitoring'
+
+// Deprecated: staticPlugin is now merged into vitePlugin (auto-detects dev/prod)
+/** @deprecated Use vitePlugin instead - it now handles both dev and prod */
+export const staticPlugin = vitePlugin
+
+// Export as a collection
+export const builtInPlugins = {
+  swagger: swaggerPlugin,
+  vite: vitePlugin,
+  static: staticPlugin,
+  monitoring: monitoringPlugin
+} as const
+
+// Export as an array for easy registration
+export const builtInPluginsList = [
+  swaggerPlugin,
+  vitePlugin,
+  staticPlugin,
+  monitoringPlugin
+] as const
+
+// Plugin categories
+export const pluginCategories = {
+  core: [vitePlugin], // vitePlugin now handles both dev (Vite) and prod (static)
+  development: [vitePlugin],
+  documentation: [swaggerPlugin],
+  monitoring: [monitoringPlugin]
+} as const
+
+// Default plugin configuration
+export const defaultPluginConfig = {
+  swagger: {
+    enabled: true,
+    path: '/swagger',
+    title: 'FluxStack API',
+    description: 'Modern full-stack TypeScript framework with type-safe API endpoints'
+  },
+  vite: {
+    enabled: true,
+    port: 5173,
+    host: 'localhost',
+    checkInterval: 2000,
+    maxRetries: 10,
+    timeout: 5000
+  },
+  static: {
+    enabled: true,
+    publicDir: 'public',
+    distDir: 'dist/client',
+    indexFile: 'index.html',
+    spa: {
+      enabled: true,
+      fallback: 'index.html'
+    }
+  },
+  monitoring: {
+    enabled: false, // Disabled by default to avoid overhead
+    httpMetrics: true,
+    systemMetrics: true,
+    customMetrics: true,
+    collectInterval: 5000,
+    retentionPeriod: 300000,
+    exporters: [
+      {
+        type: 'console',
+        interval: 30000,
+        enabled: false
+      }
+    ],
+    thresholds: {
+      responseTime: 1000,
+      errorRate: 0.05,
+      memoryUsage: 0.8,
+      cpuUsage: 0.8
+    }
+  }
+} as const
+
+/**
+ * Get default plugins for a specific environment
+ */
+export function getDefaultPlugins(environment: 'development' | 'production' | 'test' = 'development') {
+  // vitePlugin now auto-detects dev/prod and serves appropriately
+  const basePlugins = [vitePlugin]
+
+  switch (environment) {
+    case 'development':
+      return [...basePlugins, swaggerPlugin, monitoringPlugin]
+    case 'production':
+      return [...basePlugins, monitoringPlugin]
+    case 'test':
+      return [] // Minimal plugins for testing
+    default:
+      return basePlugins
+  }
+}
+
+/**
+ * Get plugin by name
+ */
+export function getBuiltInPlugin(name: string) {
+  return builtInPlugins[name as keyof typeof builtInPlugins]
+}
+
+/**
+ * Check if a plugin is built-in
+ */
+export function isBuiltInPlugin(name: string): boolean {
+  return name in builtInPlugins
+}
+
+/**
+ * Get plugins by category
+ */
+export function getPluginsByCategory(category: keyof typeof pluginCategories) {
+  return pluginCategories[category] || []
+}
+
 export default builtInPlugins