qdadm 0.32.0 → 0.35.0

package/src/debug/components/panels/SignalsPanel.vue

@@ -0,0 +1,335 @@
+<script setup>
+/**
+ * SignalsPanel - Debug panel for signals with pattern filter
+ *
+ * Supports QuarKernel wildcard patterns:
+ * - auth:** → all auth signals (auth:login, auth:impersonate:start)
+ * - cache:** → all cache signals
+ * - *:created → all creation signals
+ * - ** → all signals (default)
+ */
+import { ref, computed, watch } from 'vue'
+import InputText from 'primevue/inputtext'
+import ObjectTree from '../ObjectTree.vue'
+
+const props = defineProps({
+  collector: { type: Object, required: true },
+  entries: { type: Array, required: true }
+})
+
+// Filter state - persisted in localStorage
+const STORAGE_KEY = 'qdadm-signals-filter'
+const STORAGE_KEY_MAX = 'qdadm-signals-max'
+const filterPattern = ref(localStorage.getItem(STORAGE_KEY) || '')
+const maxSignals = ref(parseInt(localStorage.getItem(STORAGE_KEY_MAX)) || 50)
+
+watch(filterPattern, (val) => {
+  localStorage.setItem(STORAGE_KEY, val)
+})
+
+watch(maxSignals, (val) => {
+  localStorage.setItem(STORAGE_KEY_MAX, String(val))
+})
+
+// Convert wildcard pattern to regex
+function wildcardToRegex(pattern) {
+  if (!pattern || pattern === '**') return null // No filter
+
+  // Escape regex special chars except * and :
+  let regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    // ** matches anything (including colons)
+    .replace(/\*\*/g, '.*')
+    // * matches anything except colon
+    .replace(/\*/g, '[^:]*')
+
+  return new RegExp(`^${regex}$`)
+}
+
+const filterRegex = computed(() => wildcardToRegex(filterPattern.value.trim()))
+
+// Apply filter, max limit, and reverse for top-down (newest first)
+const filteredEntries = computed(() => {
+  let result = props.entries
+  if (filterRegex.value) {
+    result = result.filter(e => filterRegex.value.test(e.name))
+  }
+  // Apply max limit (slice from end to keep newest)
+  if (maxSignals.value > 0 && result.length > maxSignals.value) {
+    result = result.slice(-maxSignals.value)
+  }
+  // Reverse for top-down display (newest first)
+  return [...result].reverse()
+})
+
+const filterStats = computed(() => {
+  const total = props.entries.length
+  const shown = filteredEntries.value.length
+  return total !== shown ? `${shown}/${total}` : `${total}`
+})
+
+// Preset filters
+const presets = [
+  { label: 'All', pattern: '' },
+  { label: 'data', pattern: 'entity:data-invalidate' },
+  { label: 'datalayer', pattern: 'entity:datalayer-invalidate' },
+  { label: 'auth', pattern: 'auth:**' },
+  { label: 'entity', pattern: 'entity:**' },
+  { label: 'toast', pattern: 'toast:**' }
+]
+
+function applyPreset(pattern) {
+  filterPattern.value = pattern
+}
+
+function formatTime(ts) {
+  const d = new Date(ts)
+  return d.toLocaleTimeString('en-US', { hour12: false }) + '.' + String(d.getMilliseconds()).padStart(3, '0')
+}
+
+// Extract domain from signal name (first segment)
+function getDomain(name) {
+  return name.split(':')[0]
+}
+
+const domainColors = {
+  auth: '#10b981',
+  cache: '#f59e0b',
+  entity: '#3b82f6',
+  toast: '#8b5cf6',
+  route: '#06b6d4',
+  error: '#ef4444'
+}
+
+function getDomainColor(name) {
+  const domain = getDomain(name)
+  return domainColors[domain] || '#6b7280'
+}
+</script>
+
+<template>
+  <div class="signals-panel">
+    <!-- Filter bar -->
+    <div class="signals-filter">
+      <div class="signals-filter-input">
+        <i class="pi pi-filter" />
+        <InputText
+          v-model="filterPattern"
+          placeholder="Filter: auth:** cache:** *:created"
+          class="filter-input"
+        />
+        <span class="signals-count">{{ filterStats }}</span>
+        <span class="signals-max-label">max</span>
+        <input
+          v-model.number="maxSignals"
+          type="number"
+          min="10"
+          max="500"
+          class="max-input"
+        />
+      </div>
+      <div class="signals-presets">
+        <button
+          v-for="p in presets"
+          :key="p.pattern"
+          class="preset-btn"
+          :class="{ 'preset-active': filterPattern === p.pattern }"
+          @click="applyPreset(p.pattern)"
+        >
+          {{ p.label }}
+        </button>
+      </div>
+    </div>
+
+    <!-- Entries list -->
+    <div class="signals-list">
+      <div v-if="filteredEntries.length === 0" class="signals-empty">
+        <i class="pi pi-inbox" />
+        <span>{{ entries.length === 0 ? 'No signals' : 'No matching signals' }}</span>
+      </div>
+
+      <div
+        v-for="(entry, idx) in filteredEntries"
+        :key="idx"
+        class="signal-entry"
+        :class="{ 'signal-new': entry._isNew }"
+      >
+        <div class="signal-header">
+          <span v-if="entry._isNew" class="signal-new-dot" title="New (unseen)" />
+          <span class="signal-time">{{ formatTime(entry.timestamp) }}</span>
+          <span class="signal-name" :style="{ color: getDomainColor(entry.name) }">
+            {{ entry.name }}
+          </span>
+        </div>
+        <div v-if="entry.data && Object.keys(entry.data).length > 0" class="signal-data">
+          <ObjectTree :data="entry.data" :expanded="false" />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.signals-panel {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.signals-filter {
+  padding: 8px 12px;
+  background: #27272a;
+  border-bottom: 1px solid #3f3f46;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.signals-filter-input {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.signals-filter-input .pi {
+  color: #71717a;
+  font-size: 12px;
+}
+
+.filter-input {
+  flex: 1;
+  font-size: 12px;
+  padding: 4px 8px;
+  background: #18181b;
+  border: 1px solid #3f3f46;
+  border-radius: 4px;
+  color: #f4f4f5;
+}
+
+.filter-input:focus {
+  border-color: #8b5cf6;
+  outline: none;
+}
+
+.signals-count {
+  font-size: 11px;
+  color: #71717a;
+  min-width: 40px;
+  text-align: right;
+}
+
+.signals-max-label {
+  font-size: 10px;
+  color: #52525b;
+  margin-left: 8px;
+}
+
+.max-input {
+  width: 50px;
+  font-size: 11px;
+  padding: 2px 4px;
+  background: #18181b;
+  border: 1px solid #3f3f46;
+  border-radius: 3px;
+  color: #a1a1aa;
+  text-align: center;
+}
+
+.max-input:focus {
+  border-color: #8b5cf6;
+  outline: none;
+  color: #f4f4f5;
+}
+
+.signals-presets {
+  display: flex;
+  gap: 4px;
+  flex-wrap: wrap;
+}
+
+.preset-btn {
+  padding: 2px 8px;
+  font-size: 10px;
+  background: #3f3f46;
+  border: none;
+  border-radius: 3px;
+  color: #a1a1aa;
+  cursor: pointer;
+}
+
+.preset-btn:hover {
+  background: #52525b;
+  color: #f4f4f5;
+}
+
+.preset-active {
+  background: #8b5cf6;
+  color: white;
+}
+
+.signals-list {
+  flex: 1;
+  overflow-y: auto;
+  padding: 4px;
+}
+
+.signals-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: #71717a;
+  gap: 8px;
+}
+
+.signal-entry {
+  padding: 6px 8px;
+  margin-bottom: 2px;
+  background: #27272a;
+  border-radius: 4px;
+  font-size: 12px;
+}
+
+.signal-entry:hover {
+  background: #3f3f46;
+}
+
+.signal-entry.signal-new {
+  border-left: 2px solid #f59e0b;
+  padding-left: 6px;
+}
+
+.signal-new-dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  background: #f59e0b;
+  border-radius: 50%;
+  margin-right: 4px;
+  flex-shrink: 0;
+}
+
+.signal-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.signal-time {
+  font-size: 10px;
+  color: #71717a;
+  font-family: monospace;
+}
+
+.signal-name {
+  font-weight: 500;
+  font-family: monospace;
+}
+
+.signal-data {
+  margin-top: 4px;
+  padding-left: 12px;
+  font-size: 11px;
+}
+</style>

package/src/debug/components/panels/index.js

@@ -6,3 +6,4 @@ export { default as AuthPanel } from './AuthPanel.vue'
 export { default as EntitiesPanel } from './EntitiesPanel.vue'
 export { default as ToastsPanel } from './ToastsPanel.vue'
 export { default as EntriesPanel } from './EntriesPanel.vue'
+export { default as SignalsPanel } from './SignalsPanel.vue'

package/src/entity/EntityManager.js

@@ -1,5 +1,5 @@
 import { PermissiveAuthAdapter } from './auth/PermissiveAdapter.js'
-import { AuthActions } from './auth/AuthAdapter.js'
+import { AuthActions } from './auth/EntityAuthAdapter.js'
 import { QueryExecutor } from '../query/QueryExecutor.js'
 
 /**
@@ -59,6 +59,7 @@ export class EntityManager {
       localFilterThreshold = null,  // Items threshold to switch to local filtering (null = use default)
       readOnly = false,             // If true, canCreate/canUpdate/canDelete return false
       warmup = true,                // If true, cache is preloaded at boot via DeferredRegistry
+      authSensitive = false,        // If true, auto-invalidate datalayer on auth events
       // Scope control
       scopeWhitelist = null,        // Array of scopes/modules that can bypass restrictions
       // Relations
@@ -85,6 +86,7 @@ export class EntityManager {
     this.localFilterThreshold = localFilterThreshold
     this._readOnly = readOnly
     this._warmup = warmup
+    this._authSensitive = authSensitive
 
     // Scope control
     this._scopeWhitelist = scopeWhitelist
@@ -174,6 +176,25 @@ export class EntityManager {
     this._signals.emitEntity(this.name, action, data)
   }
 
+  /**
+   * Emit entity:data-invalidate signal for client cache invalidation
+   *
+   * This is a unified signal for clients to know when entity data has changed.
+   * Clients can listen to `entity:data-invalidate` to refresh their views.
+   *
+   * @param {string} action - 'created', 'updated', 'deleted'
+   * @param {string|number} id - The affected record ID
+   * @private
+   */
+  _emitDataInvalidate(action, id) {
+    if (!this._signals) return
+    this._signals.emit('entity:data-invalidate', {
+      entity: this.name,
+      action,
+      id
+    })
+  }
+
   // ============ LIFECYCLE HOOKS ============
 
   /**
@@ -860,6 +881,7 @@ export class EntityManager {
         manager: this.name,
         id: result?.[this.idField]
       })
+      this._emitDataInvalidate('created', result?.[this.idField])
       return result
     }
     throw new Error(`[EntityManager:${this.name}] create() not implemented`)
@@ -896,6 +918,7 @@ export class EntityManager {
         manager: this.name,
         id
       })
+      this._emitDataInvalidate('updated', id)
       return result
     }
     throw new Error(`[EntityManager:${this.name}] update() not implemented`)
@@ -932,6 +955,7 @@ export class EntityManager {
         manager: this.name,
         id
       })
+      this._emitDataInvalidate('updated', id)
       return result
     }
     throw new Error(`[EntityManager:${this.name}] patch() not implemented`)
@@ -959,6 +983,7 @@ export class EntityManager {
         manager: this.name,
         id
       })
+      this._emitDataInvalidate('deleted', id)
       return result
     }
     throw new Error(`[EntityManager:${this.name}] delete() not implemented`)
@@ -1143,11 +1168,12 @@ export class EntityManager {
 
     const cleanups = []
 
-    // Listen for parent cache invalidation (if parents defined)
+    // Listen for parent data changes (if parents defined)
+    // When a parent entity's data changes, clear search cache to re-resolve parent fields
     if (this._parents && Object.keys(this._parents).length > 0) {
       const parentEntities = Object.values(this._parents).map(p => p.entity)
       cleanups.push(
-        this._signals.on('cache:entity:invalidated', ({ entity }) => {
+        this._signals.on('entity:data-invalidate', ({ entity }) => {
           if (parentEntities.includes(entity)) {
             this._clearSearchCache()
           }
@@ -1155,12 +1181,28 @@ export class EntityManager {
       )
     }
 
-    // Listen for targeted cache invalidation (routed by EventRouter)
-    // EntityManager only listens to its own signal, staying simple.
-    // EventRouter transforms high-level events (auth:impersonate) into targeted signals.
+    // Design choice: EntityManager-centric architecture
+    // Storages stay simple (pure data access), EntityManager owns invalidation logic.
+    //
+    // Signal: entity:datalayer-invalidate { entity, actuator? }
+    //   - entity: target entity name, '*' for all, or null/undefined for all
+    //   - actuator: source of the signal ('auth' for auth events, undefined for manual)
+    //
+    // Routing is handled by EventRouter (configured at Kernel level):
+    //   'auth:**' → { signal: 'entity:datalayer-invalidate', transform: () => ({ actuator: 'auth' }) }
+    //
+    // Only authSensitive entities react to actuator='auth' signals.
+    // All entities react to manual signals (no actuator).
+
     cleanups.push(
-      this._signals.on(`cache:entity:invalidate:${this.name}`, () => {
-        this.invalidateCache()
+      this._signals.on('entity:datalayer-invalidate', ({ entity, actuator } = {}) => {
+        // Auth-triggered: only react if authSensitive
+        if (actuator === 'auth' && !this._authSensitive) return
+
+        // Check entity match (global or targeted)
+        if (!entity || entity === '*' || entity === this.name) {
+          this.invalidateDataLayer()
+        }
       })
     )
 
@@ -1216,24 +1258,34 @@ export class EntityManager {
   }
 
   /**
-   * Invalidate the cache (call after create/update/delete)
+   * Invalidate the cache, forcing next list() to refetch
    *
-   * Emits cache:entity:invalidated signal only when cache was previously valid
-   * to avoid duplicate signals on repeated invalidation calls.
+   * Note: entity:data-invalidate signal is emitted by CRUD methods,
+   * not here (to include action and id context).
    */
   invalidateCache() {
-    const wasValid = this._cache.valid
-
     this._cache.valid = false
     this._cache.items = []
     this._cache.total = 0
     this._cache.loadedAt = null
     this._cacheLoading = null
+  }
+
+  /**
+   * Invalidate the entire data layer (cache + storage state)
+   *
+   * Called when external context changes (auth, impersonation, etc.)
+   * that may affect what data the storage returns.
+   *
+   * - Clears EntityManager cache
+   * - Calls storage.reset() if available (for storages with internal state)
+   */
+  invalidateDataLayer() {
+    this.invalidateCache()
 
-    // Emit cache invalidation signal only when cache was actually valid
-    // This prevents noise on repeated invalidation calls
-    if (wasValid && this._signals) {
-      this._signals.emit('cache:entity:invalidated', { entity: this.name })
+    // Reset storage if it supports it (e.g., clear auth tokens, cached responses)
+    if (typeof this.storage?.reset === 'function') {
+      this.storage.reset()
     }
   }
 

package/src/entity/auth/CompositeAuthAdapter.js

@@ -26,10 +26,10 @@
  * ```
  */
 
-import { AuthAdapter } from './AuthAdapter.js'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
 import { authFactory } from './factory.js'
 
-export class CompositeAuthAdapter extends AuthAdapter {
+export class CompositeAuthAdapter extends EntityAuthAdapter {
   /**
    * @param {object} config - Composite auth configuration
    * @param {AuthAdapter|string|object} config.default - Default adapter (required)

package/src/entity/auth/{AuthAdapter.js → EntityAuthAdapter.js}

@@ -1,7 +1,7 @@
 /**
- * AuthAdapter - Interface for scope and silo permission checks
+ * EntityAuthAdapter - Interface for entity-level permission checks
  *
- * Applications implement this interface to plug their authentication/authorization
+ * Applications implement this interface to plug their authorization
  * system into qdadm's EntityManager. The adapter provides two levels of permission checks:
  *
  * 1. **Scopes** (action-level): Can the user perform this action on this entity type?
@@ -10,9 +10,11 @@
  * 2. **Silos** (record-level): Can the user access this specific record?
  *    Example: Can user see invoice #123? (ownership, team membership, etc.)
  *
+ * Note: For user session authentication (login/logout), see SessionAuthAdapter.
+ *
  * Usage:
  * ```js
- * class MyAuthAdapter extends AuthAdapter {
+ * class MyEntityAuthAdapter extends EntityAuthAdapter {
  *   canPerform(entity, action) {
  *     const user = this.getCurrentUser()
  *     return user?.permissions?.includes(`${entity}:${action}`)
@@ -20,7 +22,6 @@
  *
  *   canAccessRecord(entity, record) {
  *     const user = this.getCurrentUser()
- *     // Check ownership or team membership
  *     return record.owner_id === user?.id || record.team_id === user?.team_id
  *   }
  *
@@ -32,7 +33,7 @@
  *
  * @interface
  */
-export class AuthAdapter {
+export class EntityAuthAdapter {
   /**
    * SecurityChecker instance for isGranted() delegation
    * @type {import('./SecurityChecker.js').SecurityChecker|null}
@@ -104,14 +105,11 @@ export class AuthAdapter {
    * @returns {boolean} True if user can perform the action on this entity type
    *
    * @example
-   * // Check if user can create invoices
    * adapter.canPerform('invoices', 'create') // true/false
-   *
-   * // Check if user can delete users
    * adapter.canPerform('users', 'delete') // true/false
    */
   canPerform(entity, action) {
-    throw new Error('[AuthAdapter] canPerform() must be implemented by subclass')
+    throw new Error('[EntityAuthAdapter] canPerform() must be implemented by subclass')
   }
 
   /**
@@ -121,52 +119,27 @@ export class AuthAdapter {
    * this determines if the user can access a particular record based on
    * ownership, team membership, or other business rules.
    *
-   * Called during:
-   * - get() operations
-   * - update() / patch() operations
-   * - delete() operations
-   * - list() result filtering (optional)
-   *
    * @param {string} entity - Entity name (e.g., 'users', 'invoices')
    * @param {object} record - The full entity record to check access for
    * @returns {boolean} True if user can access this specific record
    *
    * @example
-   * // Check if user can access a specific invoice
    * adapter.canAccessRecord('invoices', { id: 123, owner_id: 456, ... })
-   *
-   * @example
-   * // Common implementations:
-   * // 1. Ownership: record.owner_id === user.id
-   * // 2. Team: record.team_id === user.team_id
-   * // 3. Role: user.role === 'admin' (admins see all)
-   * // 4. Hierarchical: record.organization_id in user.organizations
    */
   canAccessRecord(entity, record) {
-    throw new Error('[AuthAdapter] canAccessRecord() must be implemented by subclass')
+    throw new Error('[EntityAuthAdapter] canAccessRecord() must be implemented by subclass')
   }
 
   /**
    * Get the current authenticated user
    *
    * Returns the user object or null if not authenticated. The user object
-   * should contain whatever information is needed for permission checks
-   * (id, role, team_id, permissions array, etc.).
+   * should contain whatever information is needed for permission checks.
    *
    * @returns {object|null} Current user object or null if not authenticated
-   *
-   * @example
-   * // Typical user object:
-   * {
-   *   id: 123,
-   *   email: 'user@example.com',
-   *   role: 'manager',
-   *   team_id: 456,
-   *   permissions: ['invoices:create', 'invoices:read', 'users:read']
-   * }
    */
   getCurrentUser() {
-    throw new Error('[AuthAdapter] getCurrentUser() must be implemented by subclass')
+    throw new Error('[EntityAuthAdapter] getCurrentUser() must be implemented by subclass')
   }
 }
 

package/src/entity/auth/PermissiveAdapter.js

@@ -1,7 +1,7 @@
 /**
  * PermissiveAuthAdapter - Default adapter that allows all operations
  *
- * This adapter is used when no custom AuthAdapter is provided to EntityManager.
+ * This adapter is used when no custom EntityAuthAdapter is provided to EntityManager.
  * It returns `true` for all permission checks, effectively disabling authorization.
  *
  * Use cases:
@@ -11,18 +11,16 @@
  * - Testing environments
  *
  * @example
- * // Explicit usage (rarely needed)
  * const adapter = new PermissiveAuthAdapter()
- *
  * adapter.canPerform('users', 'delete') // true
  * adapter.canAccessRecord('invoices', { id: 123, secret: true }) // true
  * adapter.getCurrentUser() // null
  *
- * @extends AuthAdapter
+ * @extends EntityAuthAdapter
  */
-import { AuthAdapter } from './AuthAdapter.js'
+import { EntityAuthAdapter } from './EntityAuthAdapter.js'
 
-export class PermissiveAuthAdapter extends AuthAdapter {
+export class PermissiveAuthAdapter extends EntityAuthAdapter {
   /**
    * Always allows any action on any entity type
    *