qdadm 1.13.0 → 1.19.2

package/src/kernel/SignalBus.ts

@@ -1,28 +1,36 @@
 /**
- * SignalBus - Wrapper around QuarKernel for qdadm event-driven architecture
+ * SignalBus - qdadm wiring.
  *
- * Provides a clean API for entity lifecycle events and cross-component communication.
- * Uses QuarKernel's wildcard support for flexible event subscriptions.
+ * The dispatcher itself now lives in `@quazardous/qdcore` so it can be shared
+ * with qdcms. This module re-exports the generic API and adds the qdadm
+ * application-level signal-name registry (`SIGNALS`).
  *
- * Signal naming conventions:
+ * Signal naming conventions (qdadm flavor):
  * - Generic CRUD: entity:created, entity:updated, entity:deleted
- * - Entity-specific: {entityName}:created, {entityName}:updated, {entityName}:deleted
+ * - Entity-specific: {entityName}:created, etc. — built via `buildSignal()`
+ * - Auth: auth:login, auth:logout, auth:expired
+ * - API: api:error
  *
- * Wildcard subscriptions (via QuarKernel):
- * - 'entity:*' matches entity:created, entity:updated, entity:deleted
- * - 'books:*' matches books:created, books:updated, books:deleted
- * - '*:created' matches any entity creation
+ * Wildcard subscriptions are inherited from QuarKernel:
+ * - 'entity:*' matches entity:created/updated/deleted
+ * - '*:created' matches any creation
  */
 
-import {
-  createKernel,
-  type QuarKernel,
-  type ListenerCallback,
-  type ListenerOptions,
-} from '@quazardous/quarkernel'
+export {
+  SignalBus,
+  createSignalBus,
+  buildSignal,
+  SIGNAL_ACTIONS,
+} from '@quazardous/qdcore'
+export type {
+  SignalBusOptions,
+  SignalAction,
+  EntitySignalPayload,
+} from '@quazardous/qdcore'
 
 /**
- * Signal names for entity operations
+ * qdadm signal-name registry.
+ * Application-level convention; kept in qdadm because qdcore is naming-agnostic.
  */
 export const SIGNALS = {
   // Generic entity lifecycle signals
@@ -37,136 +45,4 @@ export const SIGNALS = {
 
   // API error signals
   API_ERROR: 'api:error', // Emitted on any API error { status, message, url }
-
-  // Pattern for entity-specific signals
-  // Use buildSignal(entityName, action) for these
-} as const
-
-/**
- * Actions for entity signals
- */
-export const SIGNAL_ACTIONS = {
-  CREATED: 'created',
-  UPDATED: 'updated',
-  DELETED: 'deleted',
 } as const
-
-export type SignalAction = (typeof SIGNAL_ACTIONS)[keyof typeof SIGNAL_ACTIONS]
-
-/**
- * Build an entity-specific signal name
- */
-export function buildSignal(entityName: string, action: SignalAction): string {
-  return `${entityName}:${action}`
-}
-
-/**
- * SignalBus constructor options
- */
-export interface SignalBusOptions {
-  debug?: boolean
-}
-
-/**
- * Entity signal payload
- */
-export interface EntitySignalPayload {
-  entity: string
-  data: unknown
-}
-
-/**
- * SignalBus class - wraps QuarKernel for qdadm
- */
-export class SignalBus {
-  private _kernel: QuarKernel
-
-  constructor(options: SignalBusOptions = {}) {
-    this._kernel = createKernel({
-      delimiter: ':',
-      wildcard: true,
-      errorBoundary: true,
-      debug: options.debug ?? false,
-    })
-  }
-
-  /**
-   * Emit a signal with payload
-   */
-  async emit(signal: string, payload?: unknown): Promise<void> {
-    return this._kernel.emit(signal, payload)
-  }
-
-  /**
-   * Subscribe to a signal
-   * @returns Unbind function
-   */
-  on(signal: string, handler: ListenerCallback, options: ListenerOptions = {}): () => void {
-    return this._kernel.on(signal, handler, options)
-  }
-
-  /**
-   * Unsubscribe from a signal
-   */
-  off(signal: string, handler: ListenerCallback): void {
-    this._kernel.off(signal, handler)
-  }
-
-  /**
-   * Subscribe to a signal once
-   */
-  once(signal: string, handler: ListenerCallback, options: ListenerOptions = {}): () => void {
-    return this._kernel.once(signal, handler, options)
-  }
-
-  /**
-   * Emit an entity lifecycle signal
-   */
-  async emitEntity(entityName: string, action: SignalAction, data: unknown): Promise<void> {
-    const signal = buildSignal('entity', action)
-    await this.emit(signal, { entity: entityName, data })
-  }
-
-  /**
-   * Get listener count for a signal
-   */
-  listenerCount(signal?: string): number {
-    return (this._kernel as unknown as { listenerCount: (s?: string) => number }).listenerCount(signal)
-  }
-
-  /**
-   * Get all registered signal names
-   */
-  signalNames(): string[] {
-    return (this._kernel as unknown as { eventNames: () => string[] }).eventNames()
-  }
-
-  /**
-   * Remove all listeners
-   */
-  offAll(signal?: string): void {
-    ;(this._kernel as unknown as { offAll: (s?: string) => void }).offAll(signal)
-  }
-
-  /**
-   * Enable/disable debug mode
-   */
-  debug(enabled: boolean): void {
-    this._kernel.debug(enabled)
-  }
-
-  /**
-   * Get the underlying QuarKernel instance
-   * Used for sharing the kernel with HookRegistry
-   */
-  getKernel(): QuarKernel {
-    return this._kernel
-  }
-}
-
-/**
- * Factory function to create a SignalBus instance
- */
-export function createSignalBus(options: SignalBusOptions = {}): SignalBus {
-  return new SignalBus(options)
-}

package/src/modules/debug/AuthCollector.ts

@@ -10,7 +10,14 @@
  * Only shows content when auth is configured in the application.
  */
 
-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 { ISessionAuthAdapter, AuthUser } from '../../auth/SessionAuthAdapter'
 import type { SecurityChecker } from '../../entity/auth/SecurityChecker'
 
@@ -451,4 +458,44 @@ export class AuthCollector extends Collector<AuthEntry> {
       return null
     }
   }
+
+  override describe(): CollectorManifest {
+    return {
+      name: this.name,
+      records: false,
+      summary:
+        'Surfaces current authentication state: user, roles, permissions, hierarchy, token claims, adapter capabilities, plus a TTL-bounded log of recent auth events.',
+      entryShape: {
+        type: 'string (user|impersonated|token|user-permissions|hierarchy|role-permissions|permissions|adapter|status|error)',
+        label: 'string?',
+        message: 'string?',
+        data: 'json',
+      },
+      stateShape: {
+        recentEvents: 'AuthEvent[] (TTL-bounded)',
+        lastEvent: 'string?',
+      },
+      actions: this._builtinActionManifests(),
+    }
+  }
+
+  override snapshot(): CollectorSnapshot {
+    const entries = this.getEntries()
+    return {
+      name: this.name,
+      entries,
+      count: entries.length,
+      unseen: this.getBadge(),
+      state: {
+        recentEvents: this._recentEvents.map((e) => ({
+          type: e.type,
+          timestamp: e.timestamp.toISOString(),
+          id: e.id,
+          seen: e.seen,
+          data: e.data,
+        })),
+        lastEvent: this.getLastEvent(),
+      },
+    }
+  }
 }

package/src/modules/debug/Collector.ts

@@ -1,306 +1,20 @@
 /**
- * Collector - Base class for debug collectors
+ * Collector — qdadm re-export.
  *
- * Collectors gather data from various sources (signals, network, events)
- * and store them in a ring buffer for display in the debug panel.
- *
- * Subclasses implement specific collection strategies by overriding
- * the install() and uninstall() methods.
- *
- * @example
- * class SignalCollector extends Collector {
- *   static override collectorName = 'signals'
- *
- *   protected override _doInstall(ctx: CollectorContext) {
- *     this._unbind = ctx.signals.on('*', (event) => {
- *       this.record({ type: event.name, data: event.data })
- *     })
- *   }
- *
- *   protected override _doUninstall() {
- *     if (this._unbind) this._unbind()
- *   }
- * }
- */
-
-import type { SignalBus } from '../../kernel/SignalBus'
-import type { Orchestrator } from '../../orchestrator/Orchestrator'
-
-/**
- * Context provided to collectors during install
- */
-export interface CollectorContext {
-  signals?: SignalBus | null
-  orchestrator?: Orchestrator | null
-  router?: unknown
-  kernel?: unknown
-  [key: string]: unknown
-}
-
-/**
- * Base entry type for collector entries
- */
-export interface CollectorEntry {
-  timestamp: number
-  _isNew?: boolean
-  [key: string]: unknown
-}
-
-/**
- * Collector options
- */
-export interface CollectorOptions {
-  maxEntries?: number
-  enabled?: boolean
-  [key: string]: unknown
-}
-
-/**
- * Notify callback type
- */
-export type NotifyCallback = () => void
-
-/**
- * Debug bridge interface
- */
-export interface DebugBridgeInterface {
-  notify: () => void
-}
-
-/**
- * Base class for debug collectors
+ * The actual implementation now lives in `@quazardous/qddebug` so it can be
+ * shared with qdcms. Existing internal imports (`from './Collector'`)
+ * continue to work via this shim.
  */
-export class Collector<TEntry extends CollectorEntry = CollectorEntry> {
-  /**
-   * Collector name - override in subclass
-   * Using collectorName to avoid conflict with Function.name
-   */
-  static collectorName = 'base'
-
-  /**
-   * Whether this collector actually records (vs just displays state)
-   * Override to false for collectors that only show current state (e.g., zones, auth)
-   */
-  static records = true
-
-  options: CollectorOptions
-  maxEntries: number
-  entries: TEntry[]
-  protected _enabled: boolean
-  protected _installed: boolean
-  protected _ctx: CollectorContext | null
-  protected _seenCount: number
-  _bridge: DebugBridgeInterface | null
-  protected _notifyCallbacks: NotifyCallback[]
-
-  /**
-   * Create a new collector
-   * @param options - Collector options
-   */
-  constructor(options: CollectorOptions = {}) {
-    this.options = options
-    this.maxEntries = options.maxEntries ?? 100
-    this.entries = []
-    this._enabled = options.enabled ?? true
-    this._installed = false
-    this._ctx = null
-    this._seenCount = 0  // Number of entries that have been "seen"
-    this._bridge = null  // Set by DebugBridge when added
-    this._notifyCallbacks = []  // Direct notification subscribers
-  }
-
-  /**
-   * Check if this collector type records events (vs showing state)
-   */
-  get records(): boolean {
-    return (this.constructor as typeof Collector).records
-  }
-
-  /**
-   * Check if collector is enabled
-   */
-  get enabled(): boolean {
-    return this._enabled
-  }
-
-  /**
-   * Set enabled state - installs/uninstalls as needed
-   */
-  set enabled(value: boolean) {
-    if (this._enabled === value) return
-    this._enabled = value
-    if (this._ctx) {
-      if (value) {
-        this.install(this._ctx)
-      } else {
-        this.uninstall()
-      }
-    }
-  }
-
-  /**
-   * Toggle enabled state
-   * @returns New enabled state
-   */
-  toggle(): boolean {
-    this.enabled = !this._enabled
-    return this._enabled
-  }
-
-  /**
-   * Get collector name from static property
-   */
-  get name(): string {
-    return (this.constructor as typeof Collector).collectorName
-  }
-
-  /**
-   * Record an entry in the ring buffer
-   * Automatically adds timestamp and enforces max entries
-   * @param entry - Entry data to record
-   */
-  record(entry: Omit<TEntry, 'timestamp' | '_isNew'>): void {
-    const fullEntry = { ...entry, timestamp: Date.now(), _isNew: true } as TEntry
-    this.entries.push(fullEntry)
-    if (this.entries.length > this.maxEntries) {
-      this.entries.shift()
-      // Adjust seenCount when oldest entry is removed
-      if (this._seenCount > 0) {
-        this._seenCount--
-      }
-    }
-    // Notify bridge and direct subscribers
-    this.notifyChange()
-  }
-
-  /**
-   * Notify bridge that state has changed (for non-recording collectors)
-   * Call this when collector state changes that should trigger UI update
-   */
-  notifyChange(): void {
-    this._bridge?.notify()
-    // Call direct subscribers
-    for (const cb of this._notifyCallbacks) {
-      try {
-        cb()
-      } catch (e) {
-        console.warn('[Collector] Notify callback error:', e)
-      }
-    }
-  }
-
-  /**
-   * Subscribe to change notifications
-   * @param callback - Called when collector state changes
-   * @returns Unsubscribe function
-   */
-  onNotify(callback: NotifyCallback): () => void {
-    this._notifyCallbacks.push(callback)
-    return () => {
-      const idx = this._notifyCallbacks.indexOf(callback)
-      if (idx >= 0) this._notifyCallbacks.splice(idx, 1)
-    }
-  }
-
-  /**
-   * Get unseen count (new entries since last markAsSeen)
-   * @returns Number of unseen entries
-   */
-  getUnseenCount(): number {
-    return Math.max(0, this.entries.length - this._seenCount)
-  }
-
-  /**
-   * Get total count
-   * @returns Total number of entries
-   */
-  getTotalCount(): number {
-    return this.entries.length
-  }
-
-  /**
-   * Get badge count for UI display
-   * @param countAll - If true, return total count; otherwise unseen count
-   * @returns Number of entries
-   */
-  getBadge(countAll = false): number {
-    return countAll ? this.getTotalCount() : this.getUnseenCount()
-  }
-
-  /**
-   * Mark all current entries as seen
-   * Removes _isNew flag and updates seenCount
-   */
-  markAsSeen(): void {
-    this._seenCount = this.entries.length
-    // Remove _isNew flag from all entries
-    for (const entry of this.entries) {
-      delete entry._isNew
-    }
-  }
-
-  /**
-   * Clear all entries
-   */
-  clear(): void {
-    this.entries = []
-    this._seenCount = 0
-  }
-
-  /**
-   * Get all entries
-   * Returns a shallow copy to trigger Vue reactivity when used in computed
-   * @returns All recorded entries
-   */
-  getEntries(): TEntry[] {
-    return [...this.entries]
-  }
-
-  /**
-   * Get latest entries
-   * @param count - Number of entries to return
-   * @returns Latest entries
-   */
-  getLatest(count: number): TEntry[] {
-    return this.entries.slice(-count)
-  }
-
-  /**
-   * Install collector - subscribe to signals, events, etc.
-   * Stores context for later use. Override _doInstall in subclass.
-   * @param ctx - Context object with signals, router, etc.
-   */
-  install(ctx: CollectorContext): void {
-    this._ctx = ctx
-    this._installed = true
-    if (this._enabled) {
-      this._doInstall(ctx)
-    }
-  }
-
-  /**
-   * Uninstall collector - cleanup subscriptions
-   * Override _doUninstall in subclass to cleanup resources
-   */
-  uninstall(): void {
-    this._doUninstall()
-    this._installed = false
-  }
-
-  /**
-   * Internal install - override in subclass
-   * @param ctx - Context object
-   * @protected
-   */
-  protected _doInstall(_ctx: CollectorContext): void {
-    // Override in subclass
-  }
 
-  /**
-   * Internal uninstall - override in subclass
-   * @protected
-   */
-  protected _doUninstall(): void {
-    // Override in subclass
-  }
-}
+export {
+  Collector,
+  type CollectorEntry,
+  type CollectorContext,
+  type CollectorOptions,
+  type CollectorManifest,
+  type CollectorSnapshot,
+  type CollectorAction,
+  type CollectorActionManifest,
+  type DebugBridgeInterface,
+  type NotifyCallback,
+} from '@quazardous/qddebug'