@quazardous/qdadm 1.19.3

package/src/auth/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Auth module - User session authentication
+ *
+ * For entity-level permissions, see entity/auth/EntityAuthAdapter
+ */
+
+export {
+  SessionAuthAdapter,
+  LocalStorageSessionAuthAdapter,
+  type LoginCredentials,
+  type SessionData,
+  type AuthUser,
+  type ISessionAuthAdapter,
+  type LocalStorageAuthConfig,
+} from './SessionAuthAdapter'

package/src/chain/ActiveStack.ts

@@ -0,0 +1,154 @@
+/**
+ * ActiveStack - Sync navigation context from route (qdadm flavour).
+ *
+ * Composes a generic `Stack<EntityStackLevel>` from `@quazardous/qdcore` and
+ * adds qdadm-specific lookups (e.g. `getLevelByEntity`). The underlying levels
+ * dual-carry `name` (qdcore-aligned) and `entity` (legacy qdadm field), so all
+ * existing consumers continue to read `level.entity` unchanged.
+ *
+ * Stack only contains levels WITH IDs (entities with context).
+ * - /bots/bot-xyz/commands → stack = [bots(id:bot-xyz)]
+ * - /bots/bot-xyz/commands/cmd-123 → stack = [bots(id:bot-xyz), commands(id:cmd-123)]
+ *
+ * Signals emitted (via SignalBus):
+ * - stack:change — when stack levels change
+ *
+ * For Vue reactivity, use the `useActiveStack` composable.
+ *
+ * @example
+ * const stack = new ActiveStack(signalBus)
+ * signalBus.on('stack:change', ({ levels }) => console.log('Stack:', levels))
+ * stack.set([{ entity: 'bots', param: 'uuid', foreignKey: null, id: 'bot-123' }])
+ */
+
+import { Stack, type ContentStackLevel } from '@quazardous/qdcore'
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * qdadm stack level: entity-bound `ContentStackLevel`.
+ *
+ * `name` and `entity` always carry the same value. `name` is the qdcore-canonical
+ * field; `entity` is preserved for backwards compatibility with qdadm callers.
+ */
+export interface EntityStackLevel extends ContentStackLevel {
+  type: 'entity'
+  /** qdcore-aligned name (= entity) */
+  name: string
+  /** Entity name (e.g., 'bots', 'commands') — alias of `name` */
+  entity: string
+  /** Route param name (e.g., 'uuid', 'id') */
+  param: string
+  /** Foreign key field for parent relation (null for root) */
+  foreignKey: string | null
+  /** Entity ID from route params */
+  id: string | null
+}
+
+/**
+ * Legacy alias kept for backwards compatibility. New code should prefer
+ * {@link EntityStackLevel}.
+ */
+export type StackLevel = EntityStackLevel
+
+/**
+ * Input shape accepted by {@link ActiveStack.set} — `name` is optional and
+ * defaults to `entity` so existing callers (`{ entity, param, foreignKey, id }`)
+ * keep working without changes.
+ */
+export type EntityStackLevelInput = Omit<EntityStackLevel, 'type' | 'name'> & {
+  type?: 'entity'
+  name?: string
+}
+
+/**
+ * Stack change event payload
+ */
+export interface StackChangePayload {
+  levels: EntityStackLevel[]
+}
+
+/**
+ * Normalize loose input into a fully-typed EntityStackLevel.
+ */
+function normalize(input: EntityStackLevelInput): EntityStackLevel {
+  return {
+    type: 'entity',
+    name: input.name ?? input.entity,
+    entity: input.entity,
+    param: input.param,
+    foreignKey: input.foreignKey,
+    id: input.id,
+  }
+}
+
+export class ActiveStack {
+  private _stack: Stack<EntityStackLevel>
+
+  /**
+   * @param signalBus - Optional signal bus for events
+   */
+  constructor(signalBus: SignalBus | null = null) {
+    this._stack = new Stack<EntityStackLevel>(signalBus)
+  }
+
+  // ─── Mutators ─────────────────────────────────────────────────────────────
+
+  /**
+   * Replace entire stack (called on route change).
+   * Only emits if levels actually changed (handled by qdcore Stack).
+   * Accepts either fully-typed `EntityStackLevel` or the legacy
+   * `{ entity, param, foreignKey, id }` shape.
+   */
+  set(levels: EntityStackLevelInput[]): void {
+    this._stack.set(levels.map(normalize))
+  }
+
+  /**
+   * Clear the stack.
+   */
+  clear(): void {
+    this._stack.clear()
+  }
+
+  // ─── Accessors ────────────────────────────────────────────────────────────
+
+  getLevels(): EntityStackLevel[] {
+    return this._stack.getLevels()
+  }
+
+  getLevel(index: number): EntityStackLevel | null {
+    return this._stack.getLevel(index)
+  }
+
+  /**
+   * Get level by entity name (qdadm-specific helper).
+   */
+  getLevelByEntity(entity: string): EntityStackLevel | null {
+    return this._stack.getLevels().find(l => l.entity === entity) ?? null
+  }
+
+  getCurrent(): EntityStackLevel | null {
+    return this._stack.getCurrent()
+  }
+
+  getParent(): EntityStackLevel | null {
+    return this._stack.getParent()
+  }
+
+  getRoot(): EntityStackLevel | null {
+    return this._stack.getRoot()
+  }
+
+  getDepth(): number {
+    return this._stack.getDepth()
+  }
+
+  /**
+   * Underlying qdcore Stack instance (escape hatch for advanced use).
+   */
+  getCoreStack(): Stack<EntityStackLevel> {
+    return this._stack
+  }
+}
+
+export default ActiveStack

package/src/chain/StackHydrator.ts

@@ -0,0 +1,292 @@
+/**
+ * StackHydrator - Async hydration layer for ActiveStack
+ *
+ * Pure vanilla JS using SignalBus for events.
+ * Listens to stack:change and hydrates each level with entity data.
+ *
+ * Signals emitted:
+ * - stack:hydrated - when hydration completes (batched, emits once after all levels) { levels }
+ *
+ * For Vue reactivity, use useStackHydrator composable.
+ *
+ * @example
+ * const hydrator = new StackHydrator(activeStack, orchestrator, signalBus)
+ * signalBus.on('stack:hydrated', (event) => console.log('Hydrated:', event.data.levels))
+ */
+
+import type { Hydrator } from '@quazardous/qdcore'
+import type { ActiveStack, EntityStackLevel, StackLevel } from './ActiveStack'
+import type { Orchestrator } from '../orchestrator/Orchestrator'
+import type { SignalBus } from '../kernel/SignalBus'
+import type { EntityRecord } from '../types'
+
+/**
+ * Hydrated level with async state
+ */
+export interface HydratedLevel {
+  /** Entity name */
+  entity: string
+  /** Route param name */
+  param: string
+  /** Foreign key field */
+  foreignKey: string | null
+  /** Entity ID */
+  id: string | null
+  /** Resolves when hydrated */
+  promise: Promise<void> | null
+  /** True while fetching */
+  loading: boolean
+  /** True when data is loaded */
+  hydrated: boolean
+  /** Error if fetch failed */
+  error: Error | null
+  /** Entity data */
+  data: EntityRecord | null
+  /** Resolved label */
+  label: string | null
+}
+
+/**
+ * Hydrated levels payload
+ */
+export interface HydratedPayload {
+  levels: HydratedLevel[]
+}
+
+export class StackHydrator implements Hydrator<EntityStackLevel, HydratedLevel> {
+  private _activeStack: ActiveStack
+  private _orchestrator: Orchestrator
+  private _signalBus: SignalBus | null
+  private _levels: HydratedLevel[] = []
+  private _pendingEmit: Promise<void> | null = null
+  private _unsubscribe: (() => void) | null = null
+
+  constructor(
+    activeStack: ActiveStack,
+    orchestrator: Orchestrator,
+    signalBus: SignalBus | null = null
+  ) {
+    this._activeStack = activeStack
+    this._orchestrator = orchestrator
+    this._signalBus = signalBus
+
+    // Listen to stack changes via SignalBus
+    // QuarKernel passes (event, ctx) where event.data contains the payload
+    if (signalBus) {
+      this._unsubscribe = signalBus.on('stack:change', (event) => {
+        const levels = (event.data as { levels?: StackLevel[] })?.levels
+        if (levels) {
+          this._onStackChange(levels)
+        }
+      })
+    }
+    // Note: No initial check needed - stack is always empty at construction time
+    // The Kernel's router.afterEach will trigger stack:change after navigation
+  }
+
+  /**
+   * Cleanup
+   */
+  destroy(): void {
+    if (this._unsubscribe) {
+      this._unsubscribe()
+      this._unsubscribe = null
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Stack change handling
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Handle stack change - rebuild hydrated levels
+   * @private
+   */
+  private _onStackChange(stackLevels: StackLevel[]): void {
+    // Create new hydrated levels (each starts its own async hydration)
+    this._levels = stackLevels.map((level, index) =>
+      this._createHydratedLevel(level, index)
+    )
+    // Don't emit here - each level will emit when hydration completes
+  }
+
+  /**
+   * Create a hydrated level with its own promise
+   * @private
+   */
+  private _createHydratedLevel(stackLevel: StackLevel, _index: number): HydratedLevel {
+    const level: HydratedLevel = {
+      // Sync config (copied from stack)
+      entity: stackLevel.entity,
+      param: stackLevel.param,
+      foreignKey: stackLevel.foreignKey,
+      id: stackLevel.id,
+
+      // Async state
+      promise: null,
+      loading: false,
+      hydrated: false,
+      error: null,
+      data: null,
+      label: null,
+    }
+
+    // Start hydration and store promise
+    level.promise = this._hydrate(level)
+
+    return level
+  }
+
+  /**
+   * Hydrate a single level
+   * @private
+   */
+  private async _hydrate(level: HydratedLevel): Promise<void> {
+    // All levels in stack have IDs (that's the new contract)
+    // But check anyway for safety
+    if (!level.id) {
+      const manager = this._orchestrator?.get(level.entity)
+      level.label = manager?.labelPlural ?? level.entity
+      level.hydrated = true
+      this._scheduleEmit()
+      return
+    }
+
+    level.loading = true
+    // Don't emit on loading start - reduces signal noise
+
+    try {
+      const manager = this._orchestrator?.get(level.entity)
+      if (!manager) {
+        level.label = level.id
+        level.hydrated = true
+        level.loading = false
+        this._scheduleEmit()
+        return
+      }
+
+      // Fetch entity data
+      level.data = await manager.get(level.id)
+      level.label = manager.getEntityLabel?.(level.data) ?? level.id
+      level.hydrated = true
+    } catch (err) {
+      level.error = err instanceof Error ? err : new Error(String(err))
+      level.label = level.id // Fallback to ID
+      level.hydrated = true // Mark as hydrated even on error
+    } finally {
+      level.loading = false
+      this._scheduleEmit()
+    }
+  }
+
+  /**
+   * Schedule batched hydration signal (groups multiple level hydrations)
+   * Uses microtask to batch emissions within same tick
+   * @private
+   */
+  private _scheduleEmit(): void {
+    if (this._pendingEmit) return // Already scheduled
+
+    this._pendingEmit = Promise.resolve().then(() => {
+      this._pendingEmit = null
+      this._emit('stack:hydrated', { levels: this._levels })
+    })
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Accessors
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * All hydrated levels
+   */
+  getLevels(): HydratedLevel[] {
+    return this._levels
+  }
+
+  /**
+   * Get hydrated level by index
+   */
+  getLevel(index: number): HydratedLevel | null {
+    return this._levels[index] ?? null
+  }
+
+  /**
+   * Get hydrated level by entity name
+   */
+  getLevelByEntity(entity: string): HydratedLevel | null {
+    return this._levels.find(l => l.entity === entity) ?? null
+  }
+
+  /**
+   * Current hydrated level
+   */
+  getCurrent(): HydratedLevel | null {
+    return this._levels.at(-1) ?? null
+  }
+
+  /**
+   * Parent hydrated level
+   */
+  getParent(): HydratedLevel | null {
+    return this._levels.at(-2) ?? null
+  }
+
+  /**
+   * Root hydrated level
+   */
+  getRoot(): HydratedLevel | null {
+    return this._levels[0] ?? null
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Manual update (for pages that load their own data)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Manually set data for current level (skips fetch)
+   * Used by pages that already loaded the entity
+   */
+  setCurrentData(data: EntityRecord): void {
+    const level = this.getCurrent()
+    if (!level) return
+
+    const manager = this._orchestrator?.get(level.entity)
+    level.data = data
+    level.label = manager?.getEntityLabel?.(data) ?? level.id
+    level.hydrated = true
+    level.loading = false
+    this._scheduleEmit()
+  }
+
+  /**
+   * Manually set data for a level by entity name
+   */
+  setEntityData(entity: string, data: EntityRecord): void {
+    const level = this.getLevelByEntity(entity)
+    if (!level) return
+
+    const manager = this._orchestrator?.get(entity)
+    level.data = data
+    level.label = manager?.getEntityLabel?.(data) ?? level.id
+    level.hydrated = true
+    level.loading = false
+    this._scheduleEmit()
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Internal
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Emit event via SignalBus
+   * @private
+   */
+  private _emit(signal: string, payload: HydratedPayload): void {
+    if (this._signalBus) {
+      this._signalBus.emit(signal, payload)
+    }
+  }
+}
+
+export default StackHydrator

package/src/chain/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Chain Module - Active navigation stack management
+ *
+ * Provides:
+ * - ActiveStack: Sync container for navigation context (entity, param, foreignKey, id)
+ * - StackHydrator: Async layer for entity data and labels
+ * - useActiveStack: Composable to build and access the sync stack
+ * - useStackHydrator: Composable to access hydrated data
+ *
+ * @module chain
+ */
+
+// Sync stack (context only)
+export {
+  ActiveStack,
+  type StackLevel,
+  type EntityStackLevel,
+  type EntityStackLevelInput,
+  type StackChangePayload,
+} from './ActiveStack'
+export { useActiveStack, type UseActiveStackReturn } from './useActiveStack'
+
+// Async hydration (data + labels)
+export { StackHydrator, type HydratedLevel, type HydratedPayload } from './StackHydrator'
+export { useStackHydrator, type StackHydratorReturn } from './useStackHydrator'

package/src/chain/useActiveStack.ts

@@ -0,0 +1,120 @@
+/**
+ * useActiveStack - Access sync navigation stack
+ *
+ * Provides reactive access to the navigation stack levels.
+ * Stack is rebuilt by Kernel on route change (single source of truth).
+ *
+ * IMPORTANT: Stack only contains levels WITH IDs.
+ * - /bots/bot-xyz/commands → stack = [bots(id:bot-xyz)]
+ * - /bots/bot-xyz/commands/cmd-123 → stack = [bots(id:bot-xyz), commands(id:cmd-123)]
+ *
+ * For hydrated data (labels, entity data), use useStackHydrator.
+ *
+ * Listens to SignalBus events for reactivity:
+ * - stack:change - when stack levels change
+ */
+
+import { inject, ref, computed, onUnmounted, type ComputedRef, type Ref } from 'vue'
+import type { ActiveStack, StackLevel } from './ActiveStack'
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * Return type for useActiveStack composable
+ */
+export interface UseActiveStackReturn {
+  /** Reactive levels array */
+  levels: Ref<StackLevel[]>
+  /** Current (deepest) level */
+  current: ComputedRef<StackLevel | null>
+  /** Parent level */
+  parent: ComputedRef<StackLevel | null>
+  /** Root level */
+  root: ComputedRef<StackLevel | null>
+  /** Stack depth */
+  depth: ComputedRef<number>
+  /** Get level by index */
+  getLevel: (index: number) => StackLevel | null
+  /** Get level by entity name */
+  getLevelByEntity: (entity: string) => StackLevel | null
+  /** Get current level (sync) */
+  getCurrent: () => StackLevel | null
+  /** Get parent level (sync) */
+  getParent: () => StackLevel | null
+  /** Get all levels (sync) */
+  getLevels: () => StackLevel[]
+}
+
+export function useActiveStack(): UseActiveStackReturn {
+  const activeStack = inject<ActiveStack | undefined>('qdadmActiveStack')
+  const signalBus = inject<SignalBus | undefined>('qdadmSignals')
+
+  if (!activeStack) {
+    console.warn('[useActiveStack] ActiveStack not provided')
+    return createEmptyStack()
+  }
+
+  // Reactive state - updated via SignalBus
+  const levels = ref<StackLevel[]>([...activeStack.getLevels()])
+
+  // Subscribe to stack changes
+  // QuarKernel passes (event, ctx) where event.data contains the payload
+  let unsubscribe: (() => void) | null = null
+  if (signalBus) {
+    unsubscribe = signalBus.on('stack:change', (event) => {
+      const newLevels = (event.data as { levels?: StackLevel[] })?.levels
+      if (newLevels) {
+        // Create new array reference to trigger reactivity
+        levels.value = [...newLevels]
+      }
+    })
+  }
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    if (unsubscribe) {
+      unsubscribe()
+    }
+  })
+
+  // Computed accessors
+  const current = computed(() => levels.value.at(-1) ?? null)
+  const parent = computed(() => levels.value.at(-2) ?? null)
+  const root = computed(() => levels.value[0] ?? null)
+  const depth = computed(() => levels.value.length)
+
+  return {
+    // Computed refs (reactive)
+    levels,
+    current,
+    parent,
+    root,
+    depth,
+
+    // Sync accessors (direct from vanilla JS instance)
+    getLevel: (i: number) => activeStack.getLevel(i),
+    getLevelByEntity: (e: string) => activeStack.getLevelByEntity(e),
+    getCurrent: () => activeStack.getCurrent(),
+    getParent: () => activeStack.getParent(),
+    getLevels: () => activeStack.getLevels(),
+  }
+}
+
+/**
+ * Fallback when ActiveStack not available
+ */
+function createEmptyStack(): UseActiveStackReturn {
+  return {
+    levels: ref([]),
+    current: computed(() => null),
+    parent: computed(() => null),
+    root: computed(() => null),
+    depth: computed(() => 0),
+    getLevel: () => null,
+    getLevelByEntity: () => null,
+    getCurrent: () => null,
+    getParent: () => null,
+    getLevels: () => [],
+  }
+}
+
+export default useActiveStack