qdadm 0.29.0 → 0.31.0

package/src/debug/DebugModule.js

@@ -0,0 +1,215 @@
+/**
+ * DebugModule - Module System v2 class for debug tools integration
+ *
+ * Integrates the debug infrastructure (DebugBridge, collectors, DebugBar)
+ * into a qdadm application via the Module System.
+ *
+ * Features:
+ * - Creates and configures DebugBridge with default collectors
+ * - Registers ErrorCollector and SignalCollector automatically
+ * - Adds DebugBar component to 'app:debug' zone
+ * - Provides debug bridge via Vue's provide/inject
+ *
+ * @example
+ * import { createKernel, DebugModule } from 'qdadm'
+ *
+ * const kernel = createKernel({ debug: true })
+ * kernel.use(new DebugModule({ enabled: true }))
+ * await kernel.boot()
+ */
+
+import { h, inject, defineComponent } from 'vue'
+import { Module } from '../kernel/Module.js'
+import { createDebugBridge } from './DebugBridge.js'
+import { ErrorCollector } from './ErrorCollector.js'
+import { SignalCollector } from './SignalCollector.js'
+import { ToastCollector } from './ToastCollector.js'
+import { ZonesCollector } from './ZonesCollector.js'
+import { AuthCollector } from './AuthCollector.js'
+import { EntitiesCollector } from './EntitiesCollector.js'
+import DebugBar from './components/DebugBar.vue'
+
+/**
+ * Symbol for debug bridge injection key
+ */
+export const DEBUG_BRIDGE_KEY = Symbol('debugBridge')
+
+/**
+ * Debug zone name for the DebugBar component
+ * Prefixed with _ to hide from ZonesCollector (internal zone)
+ */
+export const DEBUG_ZONE = '_app:debug'
+
+/**
+ * Global DebugBar wrapper component
+ * Auto-injects the debug bridge - use in App.vue for app-wide debug bar
+ *
+ * @example
+ * <!-- In App.vue template -->
+ * <router-view />
+ * <QdadmDebugBar />
+ */
+export const QdadmDebugBar = defineComponent({
+  name: 'QdadmDebugBar',
+  setup() {
+    const bridge = inject(DEBUG_BRIDGE_KEY, null)
+    return () => bridge ? h(DebugBar, { bridge }) : null
+  }
+})
+
+/**
+ * DebugModule - Integrates debug tools into the application
+ */
+export class DebugModule extends Module {
+  /**
+   * Module identifier
+   * @type {string}
+   */
+  static name = 'debug'
+
+  /**
+   * No dependencies - debug module should work standalone
+   * @type {string[]}
+   */
+  static requires = []
+
+  /**
+   * Very low priority - runs last after all modules are connected
+   * This ensures all signals and routes are registered before debug tools start
+   * @type {number}
+   */
+  static priority = 1000
+
+  /**
+   * Create a new DebugModule
+   *
+   * @param {object} [options={}] - Module options
+   * @param {boolean} [options.enabled=false] - Initial enabled state for collectors
+   * @param {number} [options.maxEntries=100] - Max entries per collector
+   * @param {boolean} [options.errorCollector=true] - Include ErrorCollector
+   * @param {boolean} [options.signalCollector=true] - Include SignalCollector
+   * @param {boolean} [options.toastCollector=true] - Include ToastCollector
+   * @param {boolean} [options.zonesCollector=true] - Include ZonesCollector
+   * @param {boolean} [options.authCollector=true] - Include AuthCollector
+   * @param {boolean} [options.entitiesCollector=true] - Include EntitiesCollector
+   */
+  constructor(options = {}) {
+    super(options)
+    this._bridge = null
+    this._blockId = 'debug-bar'
+  }
+
+  /**
+   * Check if module should be enabled
+   *
+   * Debug module is enabled when:
+   * - In development mode (ctx.isDev)
+   * - OR debug option is explicitly true (ctx.debug)
+   *
+   * @param {import('../kernel/KernelContext.js').KernelContext} ctx
+   * @returns {boolean}
+   */
+  enabled(ctx) {
+    return ctx.isDev || ctx.debug
+  }
+
+  /**
+   * Connect module to kernel
+   *
+   * Creates DebugBridge, registers collectors, and sets up DebugBar zone.
+   *
+   * @param {import('../kernel/KernelContext.js').KernelContext} ctx
+   */
+  async connect(ctx) {
+    this.ctx = ctx
+
+    // Create debug bridge with options
+    this._bridge = createDebugBridge({
+      enabled: this.options.enabled ?? false
+    })
+
+    // Register default collectors
+    const collectorOptions = { maxEntries: this.options.maxEntries ?? 100 }
+
+    if (this.options.errorCollector !== false) {
+      this._bridge.addCollector(new ErrorCollector(collectorOptions))
+    }
+
+    if (this.options.signalCollector !== false) {
+      this._bridge.addCollector(new SignalCollector(collectorOptions))
+    }
+
+    if (this.options.toastCollector !== false) {
+      this._bridge.addCollector(new ToastCollector(collectorOptions))
+    }
+
+    if (this.options.zonesCollector !== false) {
+      this._bridge.addCollector(new ZonesCollector(collectorOptions))
+    }
+
+    if (this.options.authCollector !== false) {
+      this._bridge.addCollector(new AuthCollector(collectorOptions))
+    }
+
+    if (this.options.entitiesCollector !== false) {
+      this._bridge.addCollector(new EntitiesCollector(collectorOptions))
+    }
+
+    // Install collectors with context
+    this._bridge.install(ctx)
+
+    // Define the debug zone (for backwards compatibility, but don't render in it)
+    // When using debugBar shorthand in Kernel, the root wrapper handles rendering.
+    // The zone is still defined so apps can use <QdadmZone name="app:debug" />
+    // if they're not using the debugBar shorthand.
+    ctx.zone(DEBUG_ZONE)
+
+    // Only register zone block if NOT using Kernel's root wrapper approach
+    // This prevents double-rendering when debugBar shorthand is used.
+    // Note: When debugBar shorthand is used, Kernel wraps root with QdadmDebugBar.
+    // If we also register in zone, layouts with <Zone name="app:debug" /> would render twice.
+    if (!this.options._kernelManaged) {
+      ctx.block(DEBUG_ZONE, {
+        id: this._blockId,
+        component: DebugBar,
+        props: {
+          bridge: this._bridge
+        },
+        weight: 100
+      })
+    }
+
+    // Provide debug bridge for injection
+    ctx.provide(DEBUG_BRIDGE_KEY, this._bridge)
+
+    // Register global component for use in App.vue (outside authenticated routes)
+    ctx.component('QdadmDebugBar', QdadmDebugBar)
+  }
+
+  /**
+   * Disconnect module from kernel
+   *
+   * Cleans up debug bridge and removes DebugBar from zone.
+   */
+  async disconnect() {
+    // Uninstall bridge and all collectors
+    if (this._bridge) {
+      this._bridge.uninstall()
+      this._bridge = null
+    }
+
+    // Call parent to clean up signal listeners
+    await super.disconnect()
+  }
+
+  /**
+   * Get the debug bridge instance
+   *
+   * @returns {import('./DebugBridge.js').DebugBridge|null}
+   */
+  getBridge() {
+    return this._bridge
+  }
+}
+
+export default DebugModule

package/src/debug/EntitiesCollector.js

@@ -0,0 +1,376 @@
+/**
+ * EntitiesCollector - Debug collector for Entity Managers
+ *
+ * This collector displays registered entity managers and their state:
+ * - All registered managers from Orchestrator
+ * - Storage type and capabilities
+ * - Cache status (enabled, valid, items, threshold)
+ * - Permissions (readOnly, canCreate, canUpdate, canDelete)
+ * - Relations (parent, children, parents)
+ *
+ * Shows current state rather than historical events.
+ *
+ * @example
+ * const collector = new EntitiesCollector()
+ * collector.install(ctx)
+ * collector.getEntries() // [{ name: 'books', storage: 'ApiStorage', ... }, ...]
+ */
+
+import { Collector } from './Collector.js'
+
+/**
+ * Collector for Entity Manager state visualization
+ */
+export class EntitiesCollector extends Collector {
+  /**
+   * Collector name identifier
+   * @type {string}
+   */
+  static name = 'entities'
+
+  /**
+   * This collector shows state, not events
+   * @type {boolean}
+   */
+  static records = false
+
+  constructor(options = {}) {
+    super(options)
+    this._ctx = null
+    this._signalCleanups = []
+    this._lastUpdate = 0
+    // Activity tracking: store previous stats to detect changes
+    this._previousStats = new Map()  // entityName -> stats snapshot
+    this._activeEntities = new Set() // entities with unseen activity
+  }
+
+  /**
+   * Internal install - store context reference and subscribe to signals
+   * The orchestrator is accessed lazily since it may not exist at install time.
+   * @param {object} ctx - Context object
+   * @protected
+   */
+  _doInstall(ctx) {
+    this._ctx = ctx
+
+    // Subscribe to entity signals for reactive updates
+    // Uses deferred access since signals may not be ready at install time
+    this._setupSignals()
+  }
+
+  /**
+   * Setup signal listeners (deferred until signals available)
+   * @private
+   */
+  _setupSignals() {
+    const signals = this._ctx?.signals
+    if (!signals) {
+      // Retry on next tick if signals not ready
+      setTimeout(() => this._setupSignals(), 100)
+      return
+    }
+
+    // Listen to all entity lifecycle events
+    const entityCleanup = signals.on('entity:*', () => {
+      this._lastUpdate = Date.now()
+      this.notifyChange()
+    })
+    this._signalCleanups.push(entityCleanup)
+
+    // Listen to cache invalidation
+    const cacheCleanup = signals.on('cache:entity:invalidated', () => {
+      this._lastUpdate = Date.now()
+      this.notifyChange()
+    })
+    this._signalCleanups.push(cacheCleanup)
+  }
+
+  /**
+   * Internal uninstall - cleanup signal subscriptions
+   * @protected
+   */
+  _doUninstall() {
+    // Cleanup signal listeners
+    for (const cleanup of this._signalCleanups) {
+      if (typeof cleanup === 'function') cleanup()
+    }
+    this._signalCleanups = []
+    this._ctx = null
+  }
+
+  /**
+   * Get orchestrator lazily (may not exist at install time)
+   * @returns {object|null}
+   * @private
+   */
+  get _orchestrator() {
+    return this._ctx?.orchestrator ?? null
+  }
+
+  /**
+   * Get badge - show count of entities with unseen activity
+   * @returns {number}
+   */
+  getBadge() {
+    if (!this._orchestrator) return 0
+    // Check for new activity before returning badge count
+    this._detectActivity()
+    return this._activeEntities.size
+  }
+
+  /**
+   * Detect activity by comparing current stats with previous snapshot
+   * @private
+   */
+  _detectActivity() {
+    if (!this._orchestrator) return
+
+    for (const name of this._orchestrator.getRegisteredNames()) {
+      try {
+        const manager = this._orchestrator.get(name)
+        const currentStats = manager.getStats?.()
+        if (!currentStats) continue
+
+        const prevStats = this._previousStats.get(name)
+        if (!prevStats) {
+          // First time seeing this entity, store snapshot
+          this._previousStats.set(name, { ...currentStats })
+          continue
+        }
+
+        // Check if any stat changed
+        const hasChanged =
+          currentStats.list !== prevStats.list ||
+          currentStats.get !== prevStats.get ||
+          currentStats.create !== prevStats.create ||
+          currentStats.update !== prevStats.update ||
+          currentStats.delete !== prevStats.delete ||
+          currentStats.cacheHits !== prevStats.cacheHits ||
+          currentStats.cacheMisses !== prevStats.cacheMisses
+
+        if (hasChanged) {
+          this._activeEntities.add(name)
+          // Update snapshot for next comparison
+          this._previousStats.set(name, { ...currentStats })
+        }
+      } catch (e) {
+        // Skip failed managers
+      }
+    }
+  }
+
+  /**
+   * Get total count - number of registered entities
+   * @returns {number}
+   */
+  getTotalCount() {
+    if (!this._orchestrator) return 0
+    return this._orchestrator.getRegisteredNames().length
+  }
+
+  /**
+   * Get all entity information for display
+   * @returns {Array<object>} Entity info array
+   */
+  getEntries() {
+    if (!this._orchestrator) {
+      return [{ type: 'status', message: 'No orchestrator configured' }]
+    }
+
+    const names = this._orchestrator.getRegisteredNames()
+    if (names.length === 0) {
+      return [{ type: 'status', message: 'No entities registered' }]
+    }
+
+    const entries = []
+
+    for (const name of names.sort()) {
+      try {
+        const manager = this._orchestrator.get(name)
+        entries.push(this._buildEntityInfo(name, manager))
+      } catch (e) {
+        entries.push({
+          name,
+          error: e.message
+        })
+      }
+    }
+
+    return entries
+  }
+
+  /**
+   * Build entity info object from manager
+   * @param {string} name - Entity name
+   * @param {EntityManager} manager - Manager instance
+   * @returns {object} Entity info
+   * @private
+   */
+  _buildEntityInfo(name, manager) {
+    const cache = manager.getCacheInfo?.() || {}
+    const storage = manager.storage
+
+    return {
+      name,
+      hasActivity: this._activeEntities.has(name),
+      label: manager.label,
+      labelPlural: manager.labelPlural,
+      routePrefix: manager.routePrefix,
+      idField: manager.idField,
+
+      // Storage info
+      storage: {
+        type: storage?.constructor?.name || 'None',
+        endpoint: storage?.endpoint || storage?._endpoint || null,
+        capabilities: storage?.constructor?.capabilities || {}
+      },
+
+      // Cache info
+      cache: {
+        enabled: cache.enabled ?? false,
+        valid: cache.valid ?? false,
+        itemCount: cache.itemCount ?? 0,
+        total: cache.total ?? 0,
+        threshold: cache.threshold ?? 0,
+        overflow: cache.overflow ?? false,
+        loadedAt: cache.loadedAt ? new Date(cache.loadedAt).toLocaleTimeString() : null,
+        // Include cached items for inspection (limited to first 50)
+        items: this._getCacheItems(manager, 50)
+      },
+
+      // Permissions
+      permissions: {
+        readOnly: manager.readOnly,
+        canCreate: manager.canCreate?.() ?? true,
+        canUpdate: manager.canUpdate?.() ?? true,
+        canDelete: manager.canDelete?.() ?? true,
+        canList: manager.canList?.() ?? true
+      },
+
+      // Warmup
+      warmup: {
+        enabled: manager.warmupEnabled ?? false
+      },
+
+      // Operation stats
+      stats: manager.getStats?.() || {
+        list: 0,
+        get: 0,
+        create: 0,
+        update: 0,
+        delete: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        maxItemsSeen: 0,
+        maxTotal: 0
+      },
+
+      // Fields
+      fields: {
+        count: Object.keys(manager.fields || {}).length,
+        names: Object.keys(manager.fields || {}).slice(0, 10), // First 10
+        required: manager.getRequiredFields?.() || []
+      },
+
+      // Relations
+      relations: {
+        parent: manager._parent ? {
+          entity: manager._parent.entity,
+          foreignKey: manager._parent.foreignKey
+        } : null,
+        parents: Object.entries(manager._parents || {}).map(([key, config]) => ({
+          key,
+          entity: config.entity,
+          foreignKey: config.foreignKey
+        })),
+        children: Object.entries(manager._children || {}).map(([key, config]) => ({
+          key,
+          entity: config.entity,
+          endpoint: config.endpoint || null
+        }))
+      }
+    }
+  }
+
+  /**
+   * Get cached items from a manager
+   * @param {EntityManager} manager - Manager instance
+   * @param {number} limit - Max items to return
+   * @returns {Array} Cached items (limited)
+   * @private
+   */
+  _getCacheItems(manager, limit = 50) {
+    try {
+      // Try different cache access methods
+      if (manager._cache && Array.isArray(manager._cache)) {
+        return manager._cache.slice(0, limit)
+      }
+      if (manager._cacheMap && manager._cacheMap instanceof Map) {
+        return Array.from(manager._cacheMap.values()).slice(0, limit)
+      }
+      if (manager.cache && Array.isArray(manager.cache)) {
+        return manager.cache.slice(0, limit)
+      }
+      // Try getAll if available and cache is valid
+      if (manager.getCacheInfo?.()?.valid && manager._cachedItems) {
+        return manager._cachedItems.slice(0, limit)
+      }
+      return []
+    } catch (e) {
+      return []
+    }
+  }
+
+  /**
+   * Force refresh a specific entity's cache
+   * @param {string} entityName - Entity name
+   * @param {boolean} [reload=false] - If true, reload cache after invalidation
+   * @returns {Promise<boolean>} True if cache refreshed
+   */
+  async refreshCache(entityName, reload = false) {
+    if (!this._orchestrator) return false
+    try {
+      const manager = this._orchestrator.get(entityName)
+      manager.invalidateCache()
+      if (reload) {
+        await manager.ensureCache()
+      }
+      this.notifyChange()
+      return true
+    } catch (e) {
+      console.error('[EntitiesCollector] Failed to refresh cache:', e)
+      return false
+    }
+  }
+
+  /**
+   * Invalidate a specific entity's cache
+   * @param {string} entityName - Entity name
+   */
+  invalidateCache(entityName) {
+    if (!this._orchestrator) return
+    try {
+      const manager = this._orchestrator.get(entityName)
+      manager.invalidateCache()
+    } catch (e) {
+      console.error('[EntitiesCollector] Failed to invalidate cache:', e)
+    }
+  }
+
+  /**
+   * Mark all entities as seen (clear activity state)
+   * Call this when the panel is viewed
+   * Note: Does not call notifyChange() to avoid re-render loop
+   */
+  markSeen() {
+    this._activeEntities.clear()
+  }
+
+  /**
+   * Mark a specific entity as seen
+   * @param {string} entityName - Entity name
+   */
+  markEntitySeen(entityName) {
+    this._activeEntities.delete(entityName)
+  }
+}

package/src/debug/ErrorCollector.js

@@ -0,0 +1,66 @@
+/**
+ * ErrorCollector - Captures JavaScript errors and unhandled promise rejections
+ *
+ * This collector listens to global window error events and unhandled promise
+ * rejections, recording them for display in the debug panel.
+ *
+ * @example
+ * const collector = new ErrorCollector()
+ * collector.install(ctx)
+ * // Errors are now automatically recorded
+ * // Later...
+ * collector.uninstall()
+ */
+
+import { Collector } from './Collector.js'
+
+/**
+ * Collector for JavaScript errors and unhandled promise rejections
+ */
+export class ErrorCollector extends Collector {
+  /**
+   * Collector name identifier
+   * @type {string}
+   */
+  static name = 'errors'
+
+  /**
+   * Internal install - subscribe to error and unhandledrejection events
+   * @param {object} ctx - Context object (not used for error collection)
+   * @protected
+   */
+  _doInstall(ctx) {
+    this._handler = (event) => {
+      this.record({
+        message: event.message,
+        filename: event.filename,
+        lineno: event.lineno,
+        colno: event.colno,
+        error: event.error?.stack
+      })
+    }
+    this._rejectionHandler = (event) => {
+      this.record({
+        message: 'Unhandled Promise Rejection',
+        reason: String(event.reason)
+      })
+    }
+    window.addEventListener('error', this._handler)
+    window.addEventListener('unhandledrejection', this._rejectionHandler)
+  }
+
+  /**
+   * Internal uninstall - remove event listeners
+   * @protected
+   */
+  _doUninstall() {
+    if (this._handler) {
+      window.removeEventListener('error', this._handler)
+      this._handler = null
+    }
+    if (this._rejectionHandler) {
+      window.removeEventListener('unhandledrejection', this._rejectionHandler)
+      this._rejectionHandler = null
+    }
+  }
+}