qdadm 1.13.0 → 1.19.2

package/src/modules/debug/DebugBridge.ts

@@ -1,175 +1,14 @@
 /**
- * DebugBridge - Central aggregator for debug collectors
+ * DebugBridge — qdadm re-export.
  *
- * Manages multiple collectors and provides a unified interface
- * for the debug panel UI. Uses Vue reactivity for state management.
- *
- * @example
- * import { createDebugBridge, SignalCollector } from '@qdadm/core/debug'
- *
- * const debug = createDebugBridge()
- * debug.addCollector(new SignalCollector())
- * debug.install(ctx)
- */
-
-import { ref, shallowReactive, type Ref, type ShallowReactive } from 'vue'
-import type { Collector, CollectorContext } from './Collector'
-
-/**
- * Debug bridge options
+ * The actual implementation now lives in `@quazardous/qddebug` so it can be
+ * shared with qdcms.
  */
-export interface DebugBridgeOptions {
-  enabled?: boolean
-}
-
-/**
- * Central aggregator for debug collectors
- */
-export class DebugBridge {
-  options: DebugBridgeOptions
-  enabled: Ref<boolean>
-  collectors: ShallowReactive<Map<string, Collector>>
-  tick: Ref<number>
-  private _installed: boolean = false
-  private _ctx: CollectorContext | null = null
-
-  /**
-   * Create a new DebugBridge
-   * @param options - Bridge options
-   */
-  constructor(options: DebugBridgeOptions = {}) {
-    this.options = options
-    this.enabled = ref(options.enabled ?? false)
-    // Use shallowReactive to avoid deep reactivity on collector instances
-    this.collectors = shallowReactive(new Map())
-    // Reactive tick for UI updates - collectors increment this when they have new data
-    this.tick = ref(0)
-  }
-
-  /**
-   * Notify that a collector has new data
-   * Called by collectors when they record new entries or state changes
-   */
-  notify(): void {
-    // Defensive check - ensure tick is still a ref
-    if (this.tick && typeof this.tick === 'object' && 'value' in this.tick) {
-      this.tick.value++
-    }
-  }
 
-  /**
-   * Add a collector to the bridge
-   * @param collector - Collector instance to add
-   * @returns this for chaining
-   */
-  addCollector(collector: Collector): this {
-    const name = (collector.constructor as typeof Collector).collectorName || collector.name
-    // Set bridge reference for reactive notifications
-    collector._bridge = this
-    this.collectors.set(name, collector)
-    if (this._installed && this.enabled.value && this._ctx) {
-      collector.install(this._ctx)
-    }
-    return this
-  }
-
-  /**
-   * Get a collector by name
-   * @param name - Collector name
-   * @returns The collector or undefined
-   */
-  getCollector(name: string): Collector | undefined {
-    return this.collectors.get(name)
-  }
-
-  /**
-   * Get all collectors
-   * @returns All collectors
-   */
-  getAllCollectors(): Map<string, Collector> {
-    return this.collectors
-  }
-
-  /**
-   * Install all collectors
-   * @param ctx - Context object with signals, router, etc.
-   * @returns this for chaining
-   */
-  install(ctx: CollectorContext): this {
-    this._ctx = ctx
-    this._installed = true
-    if (this.enabled.value) {
-      for (const collector of this.collectors.values()) {
-        collector.install(ctx)
-      }
-    }
-    // Initial notify after all collectors are installed
-    // Use nextTick to ensure Vue reactivity is ready
-    setTimeout(() => this.notify(), 0)
-    return this
-  }
-
-  /**
-   * Uninstall all collectors and cleanup
-   */
-  uninstall(): void {
-    for (const collector of this.collectors.values()) {
-      collector.uninstall()
-    }
-    this.collectors.clear()
-    this._installed = false
-    this._ctx = null
-  }
-
-  /**
-   * Toggle enabled state
-   * When enabled, installs all collectors; when disabled, uninstalls them
-   * @returns New enabled state
-   */
-  toggle(): boolean {
-    this.enabled.value = !this.enabled.value
-    if (this._installed && this._ctx) {
-      if (this.enabled.value) {
-        for (const collector of this.collectors.values()) {
-          collector.install(this._ctx)
-        }
-      } else {
-        for (const collector of this.collectors.values()) {
-          collector.uninstall()
-        }
-      }
-    }
-    return this.enabled.value
-  }
-
-  /**
-   * Clear all collectors' entries
-   */
-  clearAll(): void {
-    for (const collector of this.collectors.values()) {
-      collector.clear()
-    }
-  }
-
-  /**
-   * Get total badge count across all collectors
-   * @param countAll - If true, count all entries; otherwise unseen only
-   * @returns Total entry count
-   */
-  getTotalBadge(countAll = false): number {
-    let total = 0
-    for (const collector of this.collectors.values()) {
-      total += collector.getBadge(countAll)
-    }
-    return total
-  }
-}
-
-/**
- * Factory function to create a DebugBridge
- * @param options - Bridge options
- * @returns New DebugBridge instance
- */
-export function createDebugBridge(options: DebugBridgeOptions = {}): DebugBridge {
-  return new DebugBridge(options)
-}
+export {
+  DebugBridge,
+  createDebugBridge,
+  type DebugBridgeOptions,
+  type BridgeManifest,
+  type BridgeSnapshot,
+} from '@quazardous/qddebug'

package/src/modules/debug/DebugModule.ts

@@ -21,13 +21,19 @@ import { ZonesCollector } from './ZonesCollector'
 import { AuthCollector } from './AuthCollector'
 import { EntitiesCollector } from './EntitiesCollector'
 import { RouterCollector } from './RouterCollector'
+import { I18nCollector } from './I18nCollector'
 import DebugBar from './components/DebugBar.vue'
 import type { KernelContext } from '../../kernel/KernelContext'
 
 /**
  * Symbol for debug bridge injection key
  */
-export const DEBUG_BRIDGE_KEY = Symbol('debugBridge')
+// Symbol.for() instead of Symbol() — the latter mints a fresh
+// instance each time the module evaluates, and Vite HMR can fragment
+// a single source module into multiple live instances per importer.
+// Provider and consumer would then hold DIFFERENT symbols and the
+// inject would fall back to its default (null), defeating the bridge.
+export const DEBUG_BRIDGE_KEY = Symbol.for('qdadm.debugBridge')
 
 /**
  * Debug zone name for the DebugBar component
@@ -60,7 +66,17 @@ export interface DebugModuleOptions extends ModuleOptions {
   authCollector?: boolean
   entitiesCollector?: boolean
   routerCollector?: boolean
+  i18nCollector?: boolean
   _kernelManaged?: boolean
+  /**
+   * Existing DebugBridge to register collectors onto. When provided,
+   * the module skips its own `createDebugBridge()` AND skips
+   * `bridge.install(ctx)` — the host shell owns install timing so
+   * collectors from multiple sources (e.g. qdcms + qdadm) end up on
+   * the same bridge with a single merged install. When omitted, the
+   * module owns its bridge fully (legacy behaviour).
+   */
+  bridge?: DebugBridge
 }
 
 /**
@@ -94,8 +110,10 @@ export class DebugModule extends Module {
   override async connect(ctx: KernelContext): Promise<void> {
     this.ctx = ctx as unknown as Record<string, unknown>
 
-    // Create debug bridge with options
-    this._bridge = createDebugBridge({
+    // External bridge (host-owned) when provided — the host installs
+    // it later with a merged context. Otherwise create our own.
+    const externalBridge = this.options.bridge ?? null
+    this._bridge = externalBridge ?? createDebugBridge({
       enabled: this.options.enabled ?? false
     })
 
@@ -130,8 +148,16 @@ export class DebugModule extends Module {
       this._bridge.addCollector(new RouterCollector(collectorOptions))
     }
 
-    // Install collectors with context
-    this._bridge.install(ctx as unknown as Record<string, unknown>)
+    if (this.options.i18nCollector !== false) {
+      this._bridge.addCollector(new I18nCollector(collectorOptions))
+    }
+
+    // Install collectors with context — only when WE own the bridge.
+    // External bridges are installed by the host later with a merged
+    // context that may include data from other frameworks (e.g. cms).
+    if (!externalBridge) {
+      this._bridge.install(ctx as unknown as Record<string, unknown>)
+    }
 
     // Define the debug zone
     const extCtx = ctx as KernelContext & {
@@ -165,6 +191,10 @@ export class DebugModule extends Module {
 
     // Register global component for use in App.vue
     extCtx.component('QdadmDebugBar', QdadmDebugBar)
+
+    // The HTTP debug bridge (qdadmDebugPlugin) is wired entirely from the
+    // injected client script (see transformIndexHtml in the plugin). The
+    // DebugModule itself stays browser-pure and HMR-agnostic.
   }
 
   /**

package/src/modules/debug/EntitiesCollector.ts

@@ -11,7 +11,14 @@
  * Shows current state rather than historical events.
  */
 
-import { Collector, type CollectorContext, type CollectorEntry, type CollectorOptions } from './Collector'
+import {
+  Collector,
+  type CollectorContext,
+  type CollectorEntry,
+  type CollectorManifest,
+  type CollectorOptions,
+  type CollectorSnapshot,
+} from './Collector'
 import type { EntityManager } from '../../entity/EntityManager'
 
 /**
@@ -708,6 +715,95 @@ export class EntitiesCollector extends Collector<EntityEntry> {
     }
   }
 
+  override describe(): CollectorManifest {
+    return {
+      name: this.name,
+      records: false,
+      summary:
+        'Lists every registered EntityManager with its storage, cache state, permissions, stats, fields and relations.',
+      entryShape: {
+        name: 'string',
+        system: 'boolean',
+        hasActivity: 'boolean',
+        label: 'string?',
+        labelPlural: 'string?',
+        routePrefix: 'string?',
+        idField: 'string?',
+        storage: 'StorageInfo',
+        multiStorage: 'MultiStorageInfo?',
+        cache: 'CacheInfo',
+        permissions: 'PermissionsInfo',
+        authSensitive: 'boolean',
+        warmup: 'WarmupInfo',
+        stats: 'StatsInfo',
+        fields: 'FieldsInfo',
+        relations: 'RelationsInfo',
+      },
+      stateShape: {
+        registered: 'string[] (entity names)',
+        activeEntities: 'string[] (entities with unseen activity)',
+      },
+      actions: [
+        ...this._builtinActionManifests(),
+        {
+          name: 'refreshCache',
+          summary: 'Invalidate one entity\'s cache (and optionally reload).',
+          args: { entity: 'string', reload: 'boolean?' },
+          mutates: true,
+        },
+        {
+          name: 'invalidateCache',
+          summary: 'Mark one entity\'s cache invalid without reloading.',
+          args: { entity: 'string' },
+          mutates: true,
+        },
+        {
+          name: 'testFetch',
+          summary: 'Probe an entity\'s primary storage with a list({page:1,page_size:1}).',
+          args: { entity: 'string' },
+        },
+        {
+          name: 'testStorageFetch',
+          summary: 'Probe a specific named storage on an entity.',
+          args: { entity: 'string', storage: 'string' },
+        },
+      ],
+    }
+  }
+
+  override snapshot(): CollectorSnapshot {
+    const entries = this.getEntries()
+    const registered = this._orchestrator?.getRegisteredNames() ?? []
+    return {
+      name: this.name,
+      entries,
+      count: entries.length,
+      unseen: this.getBadge(),
+      state: {
+        registered,
+        activeEntities: Array.from(this._activeEntities),
+      },
+    }
+  }
+
+  override async call(actionName: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    if (actionName === 'refreshCache') {
+      const ok = await this.refreshCache(String(args.entity ?? ''), Boolean(args.reload))
+      return { ok }
+    }
+    if (actionName === 'invalidateCache') {
+      this.invalidateCache(String(args.entity ?? ''))
+      return { ok: true }
+    }
+    if (actionName === 'testFetch') {
+      return await this.testFetch(String(args.entity ?? ''))
+    }
+    if (actionName === 'testStorageFetch') {
+      return await this.testStorageFetch(String(args.entity ?? ''), String(args.storage ?? ''))
+    }
+    return super.call(actionName, args)
+  }
+
   /**
    * Test fetch data from a specific storage of an entity
    */

package/src/modules/debug/ErrorCollector.ts

@@ -1,79 +1,4 @@
 /**
- * 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()
+ * ErrorCollector — qdadm re-export from @quazardous/qddebug.
  */
-
-import { Collector, type CollectorContext, type CollectorEntry } from './Collector'
-
-/**
- * Error entry type
- */
-export interface ErrorEntry extends CollectorEntry {
-  message?: string
-  filename?: string
-  lineno?: number
-  colno?: number
-  error?: string
-  reason?: string
-}
-
-/**
- * Collector for JavaScript errors and unhandled promise rejections
- */
-export class ErrorCollector extends Collector<ErrorEntry> {
-  /**
-   * Collector name identifier
-   */
-  static override collectorName = 'errors'
-
-  private _handler: ((event: ErrorEvent) => void) | null = null
-  private _rejectionHandler: ((event: PromiseRejectionEvent) => void) | null = null
-
-  /**
-   * Internal install - subscribe to error and unhandledrejection events
-   * @protected
-   */
-  protected override _doInstall(_ctx: CollectorContext): void {
-    this._handler = (event: ErrorEvent) => {
-      this.record({
-        message: event.message,
-        filename: event.filename,
-        lineno: event.lineno,
-        colno: event.colno,
-        error: event.error?.stack
-      })
-    }
-    this._rejectionHandler = (event: PromiseRejectionEvent) => {
-      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
-   */
-  protected override _doUninstall(): void {
-    if (this._handler) {
-      window.removeEventListener('error', this._handler)
-      this._handler = null
-    }
-    if (this._rejectionHandler) {
-      window.removeEventListener('unhandledrejection', this._rejectionHandler)
-      this._rejectionHandler = null
-    }
-  }
-}
+export { ErrorCollector, type ErrorEntry } from '@quazardous/qddebug'

package/src/modules/debug/I18nCollector.ts

@@ -0,0 +1,9 @@
+/**
+ * I18nCollector — qdadm re-export from @quazardous/qddebug.
+ */
+export {
+  I18nCollector,
+  type MissingKeyEntry,
+  type LocaleChange,
+  type I18nCollectorOptions,
+} from '@quazardous/qddebug'

package/src/modules/debug/LocalStorageAdapter.ts

@@ -1,151 +1,7 @@
 /**
- * LocalStorageAdapter - Debug settings persistence
+ * LocalStorageAdapter — qdadm re-export.
  *
- * Persists debug bridge state (enabled, collector settings) to localStorage.
- * Allows debug settings to survive page refreshes.
- *
- * @example
- * import { createDebugBridge, LocalStorageAdapter } from '@qdadm/core/debug'
- *
- * const debug = createDebugBridge()
- * const storage = new LocalStorageAdapter('qdadm-debug')
- * storage.attach(debug) // Auto-saves on change, restores on load
- */
-
-import type { DebugBridge } from './DebugBridge'
-
-/**
- * LocalStorage adapter for debug settings persistence
+ * The actual implementation now lives in `@quazardous/qddebug`.
  */
-export class LocalStorageAdapter {
-  readonly key: string
-  private _bridge: DebugBridge | null = null
-  private _unwatch: (() => void) | null = null
-
-  /**
-   * Create a new LocalStorageAdapter
-   * @param key - localStorage key prefix
-   */
-  constructor(key = 'qdadm-debug') {
-    this.key = key
-  }
-
-  /**
-   * Get the full key for a setting
-   * @param name - Setting name
-   * @returns Full localStorage key
-   */
-  private _getKey(name: string): string {
-    return `${this.key}:${name}`
-  }
-
-  /**
-   * Get a value from localStorage
-   * @param name - Setting name
-   * @param defaultValue - Default if not found
-   * @returns The value
-   */
-  get<T>(name: string, defaultValue: T | null = null): T | null {
-    try {
-      const stored = localStorage.getItem(this._getKey(name))
-      return stored !== null ? JSON.parse(stored) : defaultValue
-    } catch {
-      return defaultValue
-    }
-  }
-
-  /**
-   * Set a value in localStorage
-   * @param name - Setting name
-   * @param value - Value to store
-   */
-  set(name: string, value: unknown): void {
-    try {
-      localStorage.setItem(this._getKey(name), JSON.stringify(value))
-    } catch {
-      // localStorage might be full or disabled
-    }
-  }
-
-  /**
-   * Remove a value from localStorage
-   * @param name - Setting name
-   */
-  remove(name: string): void {
-    localStorage.removeItem(this._getKey(name))
-  }
 
-  /**
-   * Clear all debug settings
-   */
-  clear(): void {
-    const prefix = this.key + ':'
-    const keys: string[] = []
-    for (let i = 0; i < localStorage.length; i++) {
-      const key = localStorage.key(i)
-      if (key && key.startsWith(prefix)) {
-        keys.push(key)
-      }
-    }
-    keys.forEach(key => localStorage.removeItem(key))
-  }
-
-  /**
-   * Attach to a DebugBridge and sync state
-   * Restores saved state and watches for changes
-   * @param bridge - The debug bridge to attach to
-   * @returns this for chaining
-   */
-  attach(bridge: DebugBridge): this {
-    this._bridge = bridge
-
-    // Restore saved enabled state
-    const savedEnabled = this.get<boolean>('enabled')
-    if (savedEnabled !== null && bridge.enabled.value !== savedEnabled) {
-      bridge.enabled.value = savedEnabled
-    }
-
-    // Watch for enabled changes (if Vue's watch is available)
-    // In a real Vue app, use watch from vue
-
-    return this
-  }
-
-  /**
-   * Detach from the debug bridge
-   */
-  detach(): void {
-    if (this._unwatch) {
-      this._unwatch()
-      this._unwatch = null
-    }
-    this._bridge = null
-  }
-
-  /**
-   * Save current bridge state
-   */
-  save(): void {
-    if (!this._bridge) return
-    this.set('enabled', this._bridge.enabled.value)
-  }
-
-  /**
-   * Restore bridge state from localStorage
-   */
-  restore(): void {
-    if (!this._bridge) return
-    const savedEnabled = this.get<boolean>('enabled')
-    if (savedEnabled !== null) {
-      this._bridge.enabled.value = savedEnabled
-    }
-  }
-}
-
-/**
- * Factory function to create a LocalStorageAdapter
- * @param key - localStorage key prefix
- */
-export function createLocalStorageAdapter(key?: string): LocalStorageAdapter {
-  return new LocalStorageAdapter(key)
-}
+export { LocalStorageAdapter, createLocalStorageAdapter } from '@quazardous/qddebug'