qdadm 0.17.0 → 0.25.0

package/src/kernel/Kernel.js

@@ -51,6 +51,7 @@ import { createSignalBus } from './SignalBus.js'
 import { createZoneRegistry } from '../zones/ZoneRegistry.js'
 import { registerStandardZones } from '../zones/zones.js'
 import { createHookRegistry } from '../hooks/HookRegistry.js'
+import { createSecurityChecker } from '../entity/auth/SecurityChecker.js'
 
 export class Kernel {
   /**
@@ -71,6 +72,7 @@ export class Kernel {
    * @param {object} options.features - Feature toggles { auth, poweredBy }
    * @param {object} options.primevue - PrimeVue config { plugin, theme, options }
    * @param {object} options.layouts - Layout components { list, form, dashboard, base }
+   * @param {object} options.security - Security config { role_hierarchy, role_permissions, entity_permissions }
    */
   constructor(options) {
     this.options = options
@@ -81,6 +83,7 @@ export class Kernel {
     this.zoneRegistry = null
     this.hookRegistry = null
     this.layoutComponents = null
+    this.securityChecker = null
   }
 
   /**
@@ -88,12 +91,17 @@ export class Kernel {
    * @returns {App} Vue app instance ready to mount
    */
   createApp() {
-    this._initModules()
-    this._createRouter()
+    // 1. Create services first (modules need them)
     this._createSignalBus()
     this._createHookRegistry()
-    this._createOrchestrator()
     this._createZoneRegistry()
+    // 2. Initialize modules (can use all services, registers routes)
+    this._initModules()
+    // 3. Create router (needs routes from modules)
+    this._createRouter()
+    // 4. Create orchestrator and remaining components
+    this._createOrchestrator()
+    this._setupSecurity()
     this._createLayoutComponents()
     this._createVueApp()
     this._installPlugins()
@@ -102,13 +110,19 @@ export class Kernel {
 
   /**
    * Initialize modules from glob import
+   * Passes services to modules for zone/signal/hook registration
    */
   _initModules() {
     if (this.options.sectionOrder) {
       setSectionOrder(this.options.sectionOrder)
     }
     if (this.options.modules) {
-      initModules(this.options.modules, this.options.modulesOptions || {})
+      initModules(this.options.modules, {
+        ...this.options.modulesOptions,
+        zones: this.zoneRegistry,
+        signals: this.signals,
+        hooks: this.hookRegistry
+      })
     }
   }
 
@@ -211,6 +225,44 @@ export class Kernel {
     })
   }
 
+  /**
+   * Setup security layer (role hierarchy, permissions)
+   *
+   * If security config is provided, creates a SecurityChecker and wires it
+   * into the entityAuthAdapter for isGranted() support.
+   *
+   * Security config:
+   * ```js
+   * security: {
+   *   role_hierarchy: { ROLE_ADMIN: ['ROLE_USER'] },
+   *   role_permissions: {
+   *     ROLE_USER: ['entity:read', 'entity:list'],
+   *     ROLE_ADMIN: ['entity:create', 'entity:update', 'entity:delete'],
+   *   },
+   *   entity_permissions: false  // false | true | ['books', 'loans']
+   * }
+   * ```
+   */
+  _setupSecurity() {
+    const { security, entityAuthAdapter } = this.options
+    if (!security) return
+
+    // Create SecurityChecker with role hierarchy and permissions
+    this.securityChecker = createSecurityChecker({
+      role_hierarchy: security.role_hierarchy || {},
+      role_permissions: security.role_permissions || {},
+      getCurrentUser: () => entityAuthAdapter?.getCurrentUser?.() || null
+    })
+
+    // Store entity_permissions config for EntityManager to use
+    this.securityChecker.entityPermissions = security.entity_permissions ?? false
+
+    // Wire SecurityChecker into entityAuthAdapter
+    if (entityAuthAdapter?.setSecurityChecker) {
+      entityAuthAdapter.setSecurityChecker(this.securityChecker)
+    }
+  }
+
   /**
    * Create zone registry for extensible UI composition
    * Registers standard zones during bootstrap.
@@ -386,4 +438,21 @@ export class Kernel {
   get layouts() {
     return this.layoutComponents
   }
+
+  /**
+   * Get the SecurityChecker instance
+   * @returns {import('../entity/auth/SecurityChecker.js').SecurityChecker|null}
+   */
+  getSecurityChecker() {
+    return this.securityChecker
+  }
+
+  /**
+   * Shorthand accessor for security checker
+   * Allows `kernel.security.isGranted(...)` syntax
+   * @returns {import('../entity/auth/SecurityChecker.js').SecurityChecker|null}
+   */
+  get security() {
+    return this.securityChecker
+  }
 }

package/src/module/moduleRegistry.js

@@ -1,28 +1,28 @@
 /**
  * Module Registry - Auto-discovery and registration system
  *
- * Each module can provide an init.js that registers:
- * - Routes
- * - Navigation items
- * - Route families (for active state detection)
+ * Each module provides an init.js that registers:
+ * - Routes & Navigation (via registry)
+ * - Zone blocks (via zones)
+ * - Signal handlers (via signals)
+ * - Hooks (via hooks)
  *
  * Usage in module (modules/agents/init.js):
  *
- *   export function init(registry) {
- *     registry.addRoutes('agents', [
- *       { path: '', name: 'agents', component: () => import('./pages/AgentList.vue') },
- *       { path: 'create', name: 'agent-create', component: () => import('./pages/AgentForm.vue') },
- *       { path: ':id/edit', name: 'agent-edit', component: () => import('./pages/AgentForm.vue') }
- *     ])
+ *   export function init({ registry, zones, signals, hooks }) {
+ *     // Routes & Navigation
+ *     registry.addRoutes('agents', [...])
+ *     registry.addNavItem({ section: 'Simulation', route: 'agents', ... })
+ *     registry.addRouteFamily('agents', ['agent-'])
  *
- *     registry.addNavItem({
- *       section: 'Simulation',
- *       route: 'agents',
- *       icon: 'pi pi-user',
- *       label: 'Agents'
- *     })
+ *     // Zone blocks
+ *     zones.registerBlock('agents-list-header', { id: 'agents-header', component: Header })
  *
- *     registry.addRouteFamily('agents', ['agent-'])
+ *     // Signal handlers
+ *     signals.on('agents:created', handleCreated)
+ *
+ *     // Hooks
+ *     hooks.register('agents:presave', validateAgent)
  *   }
  */
 
@@ -134,24 +134,33 @@ export function setSectionOrder(order) {
  *
  * Usage in app:
  *   const moduleInits = import.meta.glob('./modules/* /init.js', { eager: true })
- *   initModules(moduleInits)
+ *   initModules(moduleInits, { zones, signals, hooks })
  *
  * @param {object} moduleInits - Result of import.meta.glob
- * @param {object} options - { coreNavItems: [] } - Core items not in modules
+ * @param {object} options - { coreNavItems, zones, signals, hooks }
+ * @param {Array} options.coreNavItems - Core nav items not in modules
+ * @param {ZoneRegistry} options.zones - Zone registry for block registration
+ * @param {SignalBus} options.signals - Signal bus for event handlers
+ * @param {HookRegistry} options.hooks - Hook registry for lifecycle hooks
  */
 export function initModules(moduleInits, options = {}) {
+  const { coreNavItems, zones, signals, hooks } = options
+
   // Add core nav items (pages that aren't in modules)
-  if (options.coreNavItems) {
-    for (const item of options.coreNavItems) {
+  if (coreNavItems) {
+    for (const item of coreNavItems) {
       registry.addNavItem(item)
     }
   }
 
+  // Context passed to module init functions
+  const context = { registry, zones, signals, hooks }
+
   // Initialize all discovered modules
   for (const path in moduleInits) {
     const module = moduleInits[path]
     if (typeof module.init === 'function') {
-      module.init(registry)
+      module.init(context)
     }
   }
 }

package/src/query/FilterQuery.js

@@ -0,0 +1,277 @@
+/**
+ * FilterQuery - Resolves dropdown options for filters
+ *
+ * Abstracts option resolution from two sources:
+ * - 'entity': fetch options from a related EntityManager
+ * - 'field': extract distinct values from parent manager's cached items
+ *
+ * Usage:
+ * ```js
+ * // Entity source - fetch from genres EntityManager
+ * const query = new FilterQuery({
+ *   source: 'entity',
+ *   entity: 'genres',
+ *   label: 'name',
+ *   value: 'id'
+ * })
+ *
+ * // Field source - extract unique status values
+ * const query = new FilterQuery({
+ *   source: 'field',
+ *   field: 'status'
+ * })
+ *
+ * // Get options (async)
+ * const options = await query.getOptions(orchestrator)
+ * // → [{ label: 'Rock', value: 1 }, { label: 'Jazz', value: 2 }]
+ * ```
+ */
+import { getNestedValue } from './QueryExecutor.js'
+
+const VALID_SOURCES = ['entity', 'field']
+
+/**
+ * Resolve a value from an item using a path or function
+ *
+ * @param {object} item - The item to extract value from
+ * @param {string|Function} resolver - Path string ('name', 'author.country') or function (item => value)
+ * @returns {*} The resolved value
+ */
+function resolveValue(item, resolver) {
+  if (typeof resolver === 'function') {
+    return resolver(item)
+  }
+
+  // Use shared getNestedValue for path resolution
+  return getNestedValue(resolver, item)
+}
+
+export class FilterQuery {
+  /**
+   * @param {object} options
+   * @param {'entity'|'field'} options.source - Source type for options
+   * @param {string} [options.entity] - Entity name (required if source='entity')
+   * @param {string} [options.field] - Field name to extract values from (required if source='field')
+   * @param {object} [options.parentManager] - Parent EntityManager (for field source, set by builder)
+   * @param {string|Function} [options.label='name'] - Label resolver (path or function)
+   * @param {string|Function} [options.value='id'] - Value resolver (path or function)
+   * @param {Function} [options.transform] - Post-processing function for options
+   * @param {Function} [options.toQuery] - Transform filter value to query object
+   */
+  constructor(options = {}) {
+    const {
+      source,
+      entity = null,
+      field = null,
+      parentManager = null,
+      label = 'name',
+      value = 'id',
+      transform = null,
+      toQuery = null
+    } = options
+
+    // Validate source type
+    if (!source || !VALID_SOURCES.includes(source)) {
+      throw new Error(
+        `FilterQuery: source must be one of: ${VALID_SOURCES.join(', ')}. Got: ${source}`
+      )
+    }
+
+    // Validate source-specific requirements
+    if (source === 'entity' && !entity) {
+      throw new Error('FilterQuery: entity is required when source is "entity"')
+    }
+
+    if (source === 'field' && !field) {
+      throw new Error('FilterQuery: field is required when source is "field"')
+    }
+
+    this.source = source
+    this.entity = entity
+    this.field = field
+    this.parentManager = parentManager
+    this.label = label
+    this.value = value
+    this.transform = transform
+    this.toQuery = toQuery
+
+    // Internal cache
+    this._options = null
+    this._signals = null
+    this._subscriptions = []  // Signal unsubscribe functions for cleanup
+  }
+
+  /**
+   * Set the parent manager (called by useListPageBuilder for field source)
+   *
+   * @param {EntityManager} manager
+   * @returns {FilterQuery} this for chaining
+   */
+  setParentManager(manager) {
+    this.parentManager = manager
+    return this
+  }
+
+  /**
+   * Set the SignalBus for cache invalidation
+   *
+   * For entity sources, subscribes to CRUD signals ({entity}:created, {entity}:updated,
+   * {entity}:deleted) to automatically invalidate cached options when the source
+   * entity changes.
+   *
+   * @param {SignalBus} signals
+   * @returns {FilterQuery} this for chaining
+   */
+  setSignals(signals) {
+    // Clean up existing subscriptions if any
+    this._cleanupSubscriptions()
+
+    this._signals = signals
+
+    // Subscribe to entity CRUD signals for cache invalidation
+    if (this.source === 'entity' && this.entity && signals) {
+      const actions = ['created', 'updated', 'deleted']
+      for (const action of actions) {
+        const signalName = `${this.entity}:${action}`
+        const unbind = signals.on(signalName, () => this.invalidate())
+        this._subscriptions.push(unbind)
+      }
+    }
+
+    return this
+  }
+
+  /**
+   * Cleanup signal subscriptions
+   * @private
+   */
+  _cleanupSubscriptions() {
+    for (const unbind of this._subscriptions) {
+      if (typeof unbind === 'function') {
+        unbind()
+      }
+    }
+    this._subscriptions = []
+  }
+
+  /**
+   * Dispose the FilterQuery, cleaning up signal subscriptions
+   *
+   * Call this when the FilterQuery is no longer needed to prevent memory leaks.
+   */
+  dispose() {
+    this._cleanupSubscriptions()
+    this._signals = null
+    this._options = null
+  }
+
+  /**
+   * Invalidate the cached options (forces refresh on next getOptions)
+   */
+  invalidate() {
+    this._options = null
+  }
+
+  /**
+   * Get options for dropdown
+   *
+   * @param {Orchestrator} [orchestrator] - Required for entity source
+   * @returns {Promise<Array<{label: string, value: *}>>}
+   */
+  async getOptions(orchestrator = null) {
+    // Return cached options if available
+    if (this._options !== null) {
+      return this._options
+    }
+
+    let items = []
+
+    if (this.source === 'entity') {
+      items = await this._fetchFromEntity(orchestrator)
+    } else if (this.source === 'field') {
+      items = this._extractFromField()
+    }
+
+    // Map items to { label, value } format
+    let options = items.map(item => ({
+      label: resolveValue(item, this.label),
+      value: resolveValue(item, this.value)
+    }))
+
+    // Apply transform if provided
+    if (typeof this.transform === 'function') {
+      options = this.transform(options)
+    }
+
+    // Cache the result
+    this._options = options
+
+    return options
+  }
+
+  /**
+   * Fetch items from entity manager
+   *
+   * @param {Orchestrator} orchestrator
+   * @returns {Promise<Array>}
+   * @private
+   */
+  async _fetchFromEntity(orchestrator) {
+    if (!orchestrator) {
+      throw new Error('FilterQuery: orchestrator is required for entity source')
+    }
+
+    const manager = orchestrator.get(this.entity)
+    if (!manager) {
+      throw new Error(`FilterQuery: entity "${this.entity}" not found in orchestrator`)
+    }
+
+    // Fetch all items (large page_size to get everything)
+    const result = await manager.list({ page_size: 1000 })
+    return result.items || []
+  }
+
+  /**
+   * Extract unique values from parent manager's cached items
+   *
+   * @returns {Array}
+   * @private
+   */
+  _extractFromField() {
+    if (!this.parentManager) {
+      throw new Error('FilterQuery: parentManager is required for field source')
+    }
+
+    // Get cached items from parent manager
+    const cachedItems = this.parentManager._cache || []
+
+    if (cachedItems.length === 0) {
+      return []
+    }
+
+    // Extract unique values from the field
+    const seen = new Set()
+    const items = []
+
+    for (const item of cachedItems) {
+      const fieldValue = resolveValue(item, this.field)
+      if (fieldValue == null) continue
+
+      // Create a unique key for deduplication
+      const key = typeof fieldValue === 'object' ? JSON.stringify(fieldValue) : fieldValue
+
+      if (!seen.has(key)) {
+        seen.add(key)
+        // For field source, the item IS the value (create a simple object)
+        items.push({
+          [this.field]: fieldValue,
+          // Also set 'name' and 'id' defaults for simple resolution
+          name: fieldValue,
+          id: fieldValue
+        })
+      }
+    }
+
+    return items
+  }
+}