@quazardous/qdadm 1.19.3

package/src/kernel/Kernel.vue.ts

@@ -0,0 +1,304 @@
+import {
+  createApp,
+  h,
+  defineComponent,
+  ref,
+  type App,
+  type Component,
+  type Ref,
+} from 'vue'
+import { createPinia } from 'pinia'
+import ToastService from 'primevue/toastservice'
+import ConfirmationService from 'primevue/confirmationservice'
+import Tooltip from 'primevue/tooltip'
+import Toast from 'primevue/toast'
+import ToastListener from '../toast/ToastListener.vue'
+import { createQdadm } from '../plugin.js'
+import { createNotificationStore, NOTIFICATION_KEY } from '../notifications/NotificationStore'
+import { I18N_INJECTION_KEY } from '../i18n/useI18n'
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+/**
+ * Reactive reference to the debug bar component, set by the Kernel
+ * constructor when `debugBar.component` is provided.
+ *
+ * Why a window-stashed ref instead of a plain module-level export:
+ * Vite's HMR can fragment a single source module into multiple live
+ * instances (each importer getting a different `?t=…` version after
+ * HMR), so a module-level `const ref` is NOT shared across
+ * importers. Stashing the ref on `window.__qdadmDebugBarRef` (and
+ * lazy-initialising) is the only way to guarantee a single instance
+ * across all callers in dev. The Kernel writes via
+ * `setQdadmDebugBar()`; `<QdadmRoot />` reads via the same getter.
+ */
+const QDADM_DEBUG_BAR_GLOBAL_KEY = '__qdadmDebugBarRef'
+
+export function getQdadmDebugBarRef(): Ref<Component | null> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const w = typeof window !== 'undefined' ? (window as any) : null
+  if (w && w[QDADM_DEBUG_BAR_GLOBAL_KEY]) return w[QDADM_DEBUG_BAR_GLOBAL_KEY]
+  const r = ref<Component | null>(null)
+  if (w) w[QDADM_DEBUG_BAR_GLOBAL_KEY] = r
+  return r
+}
+
+/** Back-compat alias — same instance as `getQdadmDebugBarRef()`. */
+export const qdadmDebugBarRef: Ref<Component | null> = getQdadmDebugBarRef()
+
+/**
+ * Set the debug bar component reference (called from Kernel
+ * constructor). Equivalent to `getQdadmDebugBarRef().value = component`.
+ */
+export function setQdadmDebugBar(component: Component | null): void {
+  getQdadmDebugBarRef().value = component
+}
+
+/**
+ * Patch Kernel prototype with Vue app creation methods.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyVueMethods(KernelClass: { prototype: any }): void {
+  const proto = KernelClass.prototype as Self
+
+  /**
+   * Create layout components map for useLayoutResolver
+   */
+  proto._createLayoutComponents = function (this: Self): void {
+    const layouts = this.options.layouts || {}
+    this.layoutComponents = {
+      list: layouts.list || layouts.ListLayout || null,
+      form: layouts.form || layouts.FormLayout || null,
+      dashboard: layouts.dashboard || layouts.DashboardLayout || null,
+      base: layouts.base || layouts.BaseLayout || null,
+    }
+  }
+
+  /**
+   * Create Vue app instance.
+   *
+   * When `options.existingApp` is provided, the Kernel reuses the
+   * host's app and skips its own `createApp(WrappedRoot)`. The host
+   * is then responsible for rendering qdadm's DOM extras (Toast,
+   * ToastListener, DebugBar) — see `<QdadmRoot />` for a drop-in
+   * helper that does it.
+   *
+   * `options.root` is ignored in this mode (the host already mounted
+   * its own root).
+   */
+  proto._createVueApp = function (this: Self): void {
+    if (this.options.existingApp) {
+      this.vueApp = this.options.existingApp
+      return
+    }
+
+    if (!this.options.root) {
+      throw new Error('[Kernel] root component is required (or pass options.existingApp)')
+    }
+
+    const OriginalRoot = this.options.root
+    const debugBarRef = getQdadmDebugBarRef()
+    const DebugBarComponent =
+      this.options.debugBar?.component && debugBarRef.value
+        ? debugBarRef.value
+        : null
+    const hasPrimeVue = !!this.options.primevue?.plugin
+    const appKey = this._appKey
+
+    const WrappedRoot = defineComponent({
+      name: 'QdadmRootWrapper',
+      setup() {
+        return () => {
+          const children = [h(OriginalRoot, { key: appKey.value })]
+
+          if (hasPrimeVue) {
+            children.push(h(Toast))
+            children.push(h(ToastListener))
+          }
+
+          if (DebugBarComponent) {
+            children.push(h(DebugBarComponent))
+          }
+
+          return h(
+            'div',
+            { id: 'qdadm-root', style: 'display: contents' },
+            children
+          )
+        }
+      },
+    })
+
+    this.vueApp = createApp(WrappedRoot)
+  }
+
+  /**
+   * Install all plugins on Vue app.
+   *
+   * When a host shell uses `existingApp`, it may have already
+   * installed Pinia / PrimeVue / vue-router. Calling `app.use(plugin)`
+   * twice is harmless for stateless plugins (vue-router, Pinia
+   * recognise the duplicate and no-op), but PrimeVue does not — guard
+   * with `_qdadmPluginsInstalled` markers on globalProperties so the
+   * Kernel never double-installs PrimeVue, ToastService, or
+   * ConfirmationService.
+   */
+  proto._installPlugins = function (this: Self): void {
+    const app = this.vueApp!
+    const { authAdapter, features, primevue, existingApp } = this.options
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const marks = (app.config.globalProperties as any).__qdadmInstalled ??= {
+      pinia: false,
+      primevue: false,
+      router: false,
+    }
+
+    if (!marks.pinia) {
+      app.use(createPinia())
+      marks.pinia = true
+    }
+
+    if (primevue?.plugin && !marks.primevue) {
+      const pvConfig = {
+        theme: {
+          preset: primevue.theme,
+          options: {
+            darkModeSelector: '.dark-mode',
+            ...primevue.options,
+          },
+        },
+      }
+      app.use(primevue.plugin as { install: (app: App, options: unknown) => void }, pvConfig)
+      app.use(ToastService)
+      app.use(ConfirmationService)
+      app.directive('tooltip', Tooltip)
+      marks.primevue = true
+    }
+
+    // Skip vue-router install when the host owned the router from the
+    // start — they already called `app.use(router)`. Calling it again
+    // emits Vue's "Plugin has already been applied" warning. When
+    // Kernel created the router itself, install is required.
+    if (!marks.router && !this.options.existingRouter) {
+      app.use(this.router!)
+      marks.router = true
+    }
+
+    // Avoid eslint unused-var warning when host owns the app
+    void existingApp
+
+    for (const [key, value] of this._pendingProvides) {
+      app.provide(key, value)
+    }
+    this._pendingProvides.clear()
+
+    for (const [name, component] of this._pendingComponents) {
+      app.component(name, component)
+    }
+    this._pendingComponents.clear()
+
+    const { homeRoute } = this.options
+    const homeRouteName =
+      typeof homeRoute === 'object' ? homeRoute?.name : homeRoute
+
+    app.provide('qdadmZoneRegistry', this.zoneRegistry)
+    app.provide('qdadmActiveStack', this.activeStack)
+    app.provide('qdadmStackHydrator', this.stackHydrator)
+
+    if (this.options.debug && typeof window !== 'undefined') {
+      const self = this
+      // Single namespaced surface for browser-console & agent introspection.
+      // The `debug` sub-object proxies to whatever DebugBridge the DebugModule
+      // installed (resolved lazily so we don't depend on module load order).
+      const debugProxy = {
+        get bridge() {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const debugMod = (self as any).moduleLoader?.getModules?.()?.get?.('debug')
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          return debugMod?.getBridge?.() ?? (debugMod as any)?._bridge ?? null
+        },
+        describe(): unknown {
+          const b = this.bridge
+          return b ? b.describe() : null
+        },
+        dump(): unknown {
+          const b = this.bridge
+          return b ? b.dump() : null
+        },
+        call(name: string, action: string, args: Record<string, unknown> = {}): Promise<unknown> {
+          const b = this.bridge
+          if (!b) return Promise.reject(new Error('[qdadm] DebugBridge unavailable'))
+          return b.call(name, action, args)
+        },
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ;(window as any).__qdadm = {
+        kernel: this,
+        orchestrator: this.orchestrator,
+        signals: this.signals,
+        hooks: this.hookRegistry,
+        zones: this.zoneRegistry,
+        activeStack: this.activeStack,
+        stackHydrator: this.stackHydrator,
+        deferred: this.deferred,
+        router: this.router,
+        i18n: this.i18nInstance,
+        get: (name: string) => this.orchestrator!.get(name),
+        managers: () => this.orchestrator!.getRegisteredNames(),
+        debug: debugProxy,
+      }
+      console.debug(
+        '[qdadm] Debug mode: window.__qdadm.{kernel,orchestrator,signals,hooks,zones,router,i18n,debug.{describe,dump,call}}'
+      )
+    }
+
+    app.provide('qdadmSignals', this.signals)
+
+    if (this.i18nInstance) {
+      app.provide(I18N_INJECTION_KEY, this.i18nInstance)
+      app.provide('qdadmI18n', this.i18nInstance)
+    }
+
+    if (this.sseBridge) {
+      app.provide('qdadmSSEBridge', this.sseBridge)
+    }
+
+    app.provide('qdadmHooks', this.hookRegistry)
+    app.provide('qdadmDeferred', this.deferred)
+    app.provide('qdadmLayoutComponents', this.layoutComponents)
+    // Surface PrimeVue presence so host-rendered <QdadmRoot /> can
+    // decide whether to mount Toast / ToastListener.
+    app.provide('qdadmHasPrimeVue', !!primevue?.plugin)
+
+    if (this.securityChecker) {
+      app.provide('qdadmSecurityChecker', this.securityChecker)
+    }
+    if (this.permissionRegistry) {
+      app.provide('qdadmPermissionRegistry', this.permissionRegistry)
+    }
+
+    // Create and provide notification store if notifications are enabled
+    if (this.options.notifications?.enabled) {
+      this.notificationStore = createNotificationStore({
+        maxNotifications: this.options.notifications.maxNotifications,
+      })
+      app.provide(NOTIFICATION_KEY, this.notificationStore)
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const qdadmOptions: any = {
+      orchestrator: this.orchestrator,
+      authAdapter,
+      router: this.router,
+      toast: app.config.globalProperties.$toast,
+      app: this.options.app,
+      homeRoute: homeRouteName,
+      features: {
+        auth: !!authAdapter,
+        poweredBy: true,
+        ...features,
+      },
+    }
+    app.use(createQdadm(qdadmOptions) as unknown as { install: (app: App) => void })
+  }
+}

package/src/kernel/KernelContext.entities.ts

@@ -0,0 +1,80 @@
+/**
+ * Patch KernelContext prototype with entity registration methods:
+ *   - entity(name, config)   — generic EntityManager registration
+ *   - userEntity(options)    — UsersManager registration with conventions
+ */
+
+import { managerFactory, type ManagerFactoryContext } from '../entity/factory.js'
+import type { EntityManager } from '../entity/EntityManager'
+import { UsersManager } from '../security/UsersManager'
+import type { UserEntityOptions } from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyEntityMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  /**
+   * Register an entity manager.
+   *
+   * Uses managerFactory to resolve config into a manager instance.
+   * Registers with Orchestrator for CRUD operations.
+   */
+  proto.entity = function (
+    this: Self,
+    name: string,
+    config: string | Record<string, unknown> | EntityManager
+  ): Self {
+    const factoryContext = {
+      storageResolver: this._kernel.options.storageResolver,
+      managerResolver: this._kernel.options.managerResolver,
+      managerRegistry: this._kernel.options.managerRegistry || {},
+    } as ManagerFactoryContext
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const manager = managerFactory(config as any, name, factoryContext)
+
+    if (this._kernel.orchestrator) {
+      this._kernel.orchestrator.register(name, manager)
+    }
+
+    if (this._kernel.permissionRegistry) {
+      this._kernel.permissionRegistry.registerEntity(name, {
+        module: (this._module?.constructor as { name?: string })?.name || 'unknown',
+        // Register entity-own:* permissions if manager has isOwn configured
+        hasOwnership: !!(manager as unknown as { _isOwn?: unknown })._isOwn,
+      })
+    }
+
+    // Track entity → module for the 'module' i18n key strategy
+    if (this._kernel.i18nInstance) {
+      const moduleName = (this._module?.constructor as { name?: string })?.name
+      if (moduleName) {
+        this._kernel.i18nInstance.registerEntityModule(name, moduleName)
+      }
+    }
+
+    return this
+  }
+
+  /**
+   * Register a users entity with standard fields and role linking.
+   */
+  proto.userEntity = function (this: Self, options: UserEntityOptions): Self {
+    const manager = new UsersManager(options)
+
+    if (this._kernel.orchestrator) {
+      this._kernel.orchestrator.register('users', manager)
+    }
+
+    if (this._kernel.permissionRegistry) {
+      this._kernel.permissionRegistry.registerEntity('users', {
+        module: (this._module?.constructor as { name?: string })?.name || 'unknown',
+      })
+    }
+
+    return this
+  }
+}

package/src/kernel/KernelContext.events.ts

@@ -0,0 +1,57 @@
+/**
+ * Patch KernelContext prototype with event-bus / hook / deferred methods:
+ *   - on(signal, handler, options)    — signal subscription, auto-cleaned on
+ *                                        module disconnect
+ *   - hook(hookName, handler, options) — hook registration
+ *   - defer(name, factory)             — queue a deferred task
+ */
+
+import type { ListenerOptions } from '@quazardous/quarkernel'
+import type {
+  DeferredFactory,
+  HookHandler,
+  SignalHandler,
+} from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyEventMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  proto.on = function (
+    this: Self,
+    signal: string,
+    handler: SignalHandler,
+    options: ListenerOptions = {}
+  ): Self {
+    if (this._kernel.signals) {
+      const cleanup = this._kernel.signals.on(signal, handler, options)
+      // Register cleanup with module for automatic unsubscribe on disconnect
+      if (this._module && typeof this._module._addSignalCleanup === 'function') {
+        this._module._addSignalCleanup(cleanup)
+      }
+    }
+    return this
+  }
+
+  proto.hook = function (
+    this: Self,
+    hookName: string,
+    handler: HookHandler,
+    options: Record<string, unknown> = {}
+  ): Self {
+    if (this._kernel.hookRegistry) {
+      this._kernel.hookRegistry.register(hookName, handler, options)
+    }
+    return this
+  }
+
+  proto.defer = function (this: Self, name: string, factory: DeferredFactory): Self {
+    if (this._kernel.deferred) {
+      this._kernel.deferred.queue(name, factory)
+    }
+    return this
+  }
+}

package/src/kernel/KernelContext.i18n.ts

@@ -0,0 +1,37 @@
+/**
+ * Patch KernelContext prototype with i18n declarative methods:
+ *   - messages(locale, bundle)              — declare translations
+ *   - aliases(patterns)                     — declare pattern aliases
+ *   - messagesProvider(provider)            — register a TranslationProvider
+ */
+
+import type { AliasPattern, MessagesBundle, TranslationProvider } from '../i18n/types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyI18nMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  proto.messages = function (this: Self, locale: string, bundle: MessagesBundle): Self {
+    if (this._kernel.i18nInstance) {
+      this._kernel.i18nInstance.addMessages(locale, bundle)
+    }
+    return this
+  }
+
+  proto.aliases = function (this: Self, patterns: AliasPattern[]): Self {
+    if (this._kernel.i18nInstance) {
+      this._kernel.i18nInstance.addAliases(patterns)
+    }
+    return this
+  }
+
+  proto.messagesProvider = function (this: Self, provider: TranslationProvider): Self {
+    if (this._kernel.i18nInstance) {
+      this._kernel.i18nInstance.addProvider(provider)
+    }
+    return this
+  }
+}

package/src/kernel/KernelContext.permissions.ts

@@ -0,0 +1,38 @@
+/**
+ * Patch KernelContext prototype with permission registration methods:
+ *   - permissions(namespace, perms, options)   — generic registration
+ *   - entityPermissions(entity, perms)         — shorthand for entity-scoped
+ */
+
+import type { PermissionMeta, PermissionOptions } from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyPermissionMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  proto.permissions = function (
+    this: Self,
+    namespace: string,
+    permissions: Record<string, string | PermissionMeta>,
+    options: PermissionOptions = {}
+  ): Self {
+    if (this._kernel.permissionRegistry) {
+      this._kernel.permissionRegistry.register(namespace, permissions, {
+        ...options,
+        module: (this._module?.constructor as { name?: string })?.name || 'unknown',
+      })
+    }
+    return this
+  }
+
+  proto.entityPermissions = function (
+    this: Self,
+    entity: string,
+    permissions: Record<string, string | PermissionMeta>
+  ): Self {
+    return this.permissions(entity, permissions, { isEntity: true })
+  }
+}