@quazardous/qdadm 2.21.0 → 2.22.1

package/src/i18n/defaults/core.en.generated.ts

@@ -55,4 +55,24 @@ export default `core:
     invalid: Invalid value
     notFound: Not found
     unknown: An unknown error occurred
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Inherits from
+    inheritsHint: A role gets every grant of the roles it inherits from.
+    noRoles: No other role to inherit from
+    brings: "brings {count}"
+    entities: Entities
+    entity: Entity
+    all: All
+    ownRecords: own records
+    others: Other grants
+    othersHint: Wildcards and keys the registry does not know
+    covers: "covers {count}"
+    notRegistered: not registered
+    remove: Remove
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: View
+  edit: Edit
 `

package/src/i18n/defaults/core.en.yml

@@ -53,3 +53,23 @@ core:
     invalid: Invalid value
     notFound: Not found
     unknown: An unknown error occurred
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Inherits from
+    inheritsHint: A role gets every grant of the roles it inherits from.
+    noRoles: No other role to inherit from
+    brings: "brings {count}"
+    entities: Entities
+    entity: Entity
+    all: All
+    ownRecords: own records
+    others: Other grants
+    othersHint: Wildcards and keys the registry does not know
+    covers: "covers {count}"
+    notRegistered: not registered
+    remove: Remove
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: View
+  edit: Edit

package/src/i18n/defaults/core.fr.generated.ts

@@ -55,4 +55,24 @@ export default `core:
     invalid: Valeur invalide
     notFound: Introuvable
     unknown: Une erreur inconnue est survenue
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Hérite de
+    inheritsHint: Un rôle reçoit toutes les permissions des rôles dont il hérite.
+    noRoles: Aucun autre rôle dont hériter
+    brings: "apporte {count}"
+    entities: Entités
+    entity: Entité
+    all: Tout
+    ownRecords: ses propres enregistrements
+    others: Autres permissions
+    othersHint: Jokers et clés que le registre ne connaît pas
+    covers: "couvre {count}"
+    notRegistered: non enregistrée
+    remove: Retirer
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: Voir
+  edit: Modifier
 `

package/src/i18n/defaults/core.fr.yml

@@ -53,3 +53,23 @@ core:
     invalid: Valeur invalide
     notFound: Introuvable
     unknown: Une erreur inconnue est survenue
+  # RoleGrantsEditor (#2313)
+  roles:
+    inherits: Hérite de
+    inheritsHint: Un rôle reçoit toutes les permissions des rôles dont il hérite.
+    noRoles: Aucun autre rôle dont hériter
+    brings: "apporte {count}"
+    entities: Entités
+    entity: Entité
+    all: Tout
+    ownRecords: ses propres enregistrements
+    others: Autres permissions
+    othersHint: Jokers et clés que le registre ne connaît pas
+    covers: "couvre {count}"
+    notRegistered: non enregistrée
+    remove: Retirer
+    via: "via {origin}"
+# The breadcrumb's View↔Edit toggle (useNavContext).
+breadcrumb:
+  view: Voir
+  edit: Modifier

package/src/index.ts

@@ -262,6 +262,7 @@ export {
 } from './composables/usePageTitle'
 export { useApp, type UseAppReturn } from './composables/useApp'
 export { useAuth, type UseAuthReturn } from './composables/useAuth'
+export { useSecurity, type UseSecurityReturn } from './composables/useSecurity'
 export {
   useEntityItemPage,
   type UseEntityItemPageOptions,

package/src/kernel/Kernel.routing.ts

@@ -7,6 +7,7 @@ import {
   type RouteRecordNormalized,
 } from 'vue-router'
 import { getRoutes } from '../module/moduleRegistry'
+import { installChunkReload } from './chunkReload'
 import type { Kernel } from './Kernel'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
@@ -148,6 +149,20 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
     })
   }
 
+  /**
+   * A lazy page whose chunk is gone, typically after a deploy (#2295): reload once, then say so.
+   */
+  proto._setupChunkReload = function (this: Self): void {
+    installChunkReload(this.router!, {
+      notify: () =>
+        this.orchestrator!.toast.error(
+          'A new version is available',
+          'This page could not be loaded. Reload the page to get the new version.',
+          { life: 0, emitter: 'Kernel' }
+        ),
+    })
+  }
+
   /**
    * Setup auth guard on router
    */
@@ -190,7 +205,9 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
       )
 
       if (requiresAuth && !authAdapter.isAuthenticated()) {
-        if (wasEverAuthenticated) {
+        // Only a session this tab had can be lost: a first visit goes to login without the flag (#2292).
+        const sessionLost = wasEverAuthenticated
+        if (sessionLost) {
           const debug = this.options.debug ?? false
           if (debug) {
             console.warn(
@@ -204,9 +221,8 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
           wasEverAuthenticated = false
         }
 
-        return this.router!.hasRoute('login')
-          ? { name: 'login', query: { session_lost: '1' } }
-          : '/'
+        if (!this.router!.hasRoute('login')) return '/'
+        return sessionLost ? { name: 'login', query: { session_lost: '1' } } : { name: 'login' }
       }
 
       const entity = to.meta?.entity as string | undefined

package/src/kernel/Kernel.ts

@@ -228,6 +228,7 @@ export class Kernel {
     this._createRouter()
     this._setupStackSync()
     this._setupAuthGuard()
+    this._setupChunkReload()
     this._setupAuthExpiredHandler()
     this._setupAuthImpersonation()
     this._setupAuthInvalidation()
@@ -262,6 +263,7 @@ export class Kernel {
     this._createRouter()
     this._setupStackSync()
     this._setupAuthGuard()
+    this._setupChunkReload()
     this._setupAuthExpiredHandler()
     this._setupAuthImpersonation()
     this._setupAuthInvalidation()
@@ -467,6 +469,7 @@ export interface Kernel {
   // Routing (Kernel.routing.ts)
   _createRouter(): void
   _setupAuthGuard(): void
+  _setupChunkReload(): void
   _setupStackSync(): void
   _rebuildActiveStack(route: RouteLocationNormalized): void
 

package/src/kernel/Kernel.vue.ts

@@ -17,6 +17,7 @@ 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'
+import { warnWithoutQdadmVitePlugin } from './vitePluginCheck'
 import type { Kernel } from './Kernel'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
@@ -197,6 +198,8 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
    * ConfirmationService.
    */
   proto._installPlugins = function (this: Self): void {
+    // Before PrimeVue: without the vite plugin, PrimeVue is what fails, without naming qdadm (#2259).
+    warnWithoutQdadmVitePlugin()
     const app = this.vueApp!
     const { authAdapter, features, primevue, existingApp } = this.options
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/kernel/chunkReload.ts

@@ -0,0 +1,110 @@
+/**
+ * A lazy page whose chunk no longer exists (#2295), typically in a tab left open across a deploy: the build renamed
+ * its hashed chunks, the tab still runs the old bundle, and the import 404s. The router aborts the navigation and
+ * nothing tells the user; on a first load the screen stays blank.
+ *
+ * The page reloads once, at the URL the user was going to, which fetches the new index.html. A flag in
+ * sessionStorage keeps a chunk that is really missing from reloading in a loop: a second failure is reported
+ * instead. The flag is cleared by the next navigation that succeeds.
+ */
+import type { Router } from 'vue-router'
+
+export const CHUNK_RELOAD_KEY = 'qdadm:chunk-reload'
+
+// Chrome, Firefox, Safari, Vite's preload helper, webpack.
+const CHUNK_ERROR =
+  /Failed to fetch dynamically imported module|error loading dynamically imported module|Importing a module script failed|Unable to preload CSS|ChunkLoadError|Loading chunk \S+ failed/i
+
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false
+  const { name, message } = error as { name?: unknown; message?: unknown }
+  return CHUNK_ERROR.test(`${String(name ?? '')} ${typeof message === 'string' ? message : String(error)}`)
+}
+
+type FlagStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+
+export interface ChunkReloadOptions {
+  /** A second failure, or no way to guard a reload: tell the user. */
+  notify(error: unknown): void
+  /** Default: sessionStorage. Without one, nothing reloads: a loop could not be stopped. */
+  storage?: FlagStorage | null
+  /** Default: load `href` for real. */
+  reload?(href: string): void
+  /** Where Vite dispatches `vite:preloadError`. Default: window. */
+  target?: EventTarget | null
+}
+
+function sessionFlags(): FlagStorage | null {
+  try {
+    return typeof sessionStorage === 'undefined' ? null : sessionStorage
+  } catch {
+    return null
+  }
+}
+
+function reloadAt(href: string): void {
+  const url = new URL(href, window.location.href).href
+  // The failed navigation never changed the URL; the reload must land where the user was going.
+  if (url !== window.location.href) window.history.pushState(null, '', url)
+  window.location.reload()
+}
+
+/** Returns a function that removes the handlers. */
+export function installChunkReload(router: Router, options: ChunkReloadOptions): () => void {
+  const storage = options.storage === undefined ? sessionFlags() : options.storage
+  const reload = options.reload ?? reloadAt
+  const target = options.target === undefined ? (typeof window === 'undefined' ? null : window) : options.target
+  let reloading = false
+
+  const failed = (error: unknown, href: string | null) => {
+    if (reloading) return
+    let tried = true
+    try {
+      tried = !storage || storage.getItem(CHUNK_RELOAD_KEY) !== null
+      if (!tried) storage!.setItem(CHUNK_RELOAD_KEY, String(Date.now()))
+    } catch {
+      tried = true
+    }
+    if (tried) {
+      console.error('[qdadm] a page could not be loaded, and reloading did not help', error)
+      options.notify(error)
+      return
+    }
+    reloading = true
+    console.warn('[qdadm] a page could not be loaded, probably a new deploy: reloading once', error)
+    reload(href ?? (typeof window === 'undefined' ? '/' : window.location.href))
+  }
+
+  let routerSaw = false
+  const removeOnError = router.onError((error, to) => {
+    if (!isChunkLoadError(error)) return
+    routerSaw = true
+    failed(error, to ? router.resolve(to).href : null)
+  })
+  const removeAfterEach = router.afterEach((_to, _from, failure) => {
+    if (failure || reloading) return
+    try {
+      storage?.removeItem(CHUNK_RELOAD_KEY)
+    } catch {
+      /* nothing to clear */
+    }
+  })
+
+  // Vite dispatches this before the import rejects. When the import belongs to a navigation, the router hears the
+  // rejection a few microtasks later and handles it with the page the user wanted; waiting one task lets it go
+  // first, and the failure is then not handled twice.
+  const onPreloadError = (event: Event) => {
+    const error = (event as Event & { payload?: unknown }).payload ?? event
+    routerSaw = false
+    setTimeout(() => {
+      if (!routerSaw) failed(error, null)
+    }, 0)
+  }
+  target?.addEventListener('vite:preloadError', onPreloadError)
+
+  return () => {
+    removeOnError()
+    removeAfterEach()
+    target?.removeEventListener('vite:preloadError', onPreloadError)
+  }
+}

package/src/kernel/vitePluginCheck.ts

@@ -0,0 +1,61 @@
+/**
+ * Is `qdadmVitePlugin()` in the app's vite config? (#2259)
+ *
+ * qdadm ships raw sources (ADR 0003), and `qdadmVitePlugin()` is what makes the app and qdadm share one copy
+ * of PrimeVue. Without it the app dies at boot on PrimeVue's own `No PrimeVue Toast provided!`, which never
+ * names qdadm. The plugin defines `__QDADM_VITE_PLUGIN__`; the kernel checks it once, in dev, and says what to
+ * add — a log, not a throw, so an app that wires the same config by hand still boots.
+ */
+declare const __QDADM_VITE_PLUGIN__: boolean | undefined
+
+export const MISSING_VITE_PLUGIN_HINT =
+  'qdadmVitePlugin() is missing from vite.config: without it the app and qdadm can load two copies of PrimeVue, ' +
+  "and the app then fails at boot. Add it — import { qdadmVitePlugin } from '@quazardous/qdadm/vite', then " +
+  'plugins: [vue(), qdadmVitePlugin()] — see https://github.com/quazardous/qdadm#quick-start'
+
+/** Whether the app was built with the plugin: the define it sets. */
+export function hasQdadmVitePlugin(): boolean {
+  try {
+    return typeof __QDADM_VITE_PLUGIN__ !== 'undefined' && __QDADM_VITE_PLUGIN__ === true
+  } catch {
+    return false
+  }
+}
+
+const isDev = (): boolean => (import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV === true
+
+let warned = false
+
+export interface VitePluginCheckOptions {
+  /** Test seams: what the build says, and where the hint goes. */
+  present?: boolean
+  dev?: boolean
+  log?: (message: string) => void
+}
+
+/** Log the hint once, in dev, when the plugin is missing. True when it did. */
+export function warnWithoutQdadmVitePlugin(options: VitePluginCheckOptions = {}): boolean {
+  const present = options.present ?? hasQdadmVitePlugin()
+  const dev = options.dev ?? isDev()
+  if (present || !dev || warned) return false
+  warned = true
+  ;(options.log ?? console.error)(`[qdadm] ${MISSING_VITE_PLUGIN_HINT}`)
+  return true
+}
+
+/** Test seam: forget that the hint was logged. */
+export function resetVitePluginWarning(): void {
+  warned = false
+}
+
+/** PrimeVue's "No PrimeVue Toast provided!", with its usual cause named. Any other error passes through. */
+export function explainMissingToast<T>(use: () => T): T {
+  try {
+    return use()
+  } catch (e) {
+    if (e instanceof Error && /No PrimeVue Toast provided/i.test(e.message)) {
+      throw new Error(`${e.message} The usual cause: ${MISSING_VITE_PLUGIN_HINT}`)
+    }
+    throw e
+  }
+}

package/src/modules/debug/DebugModule.ts

@@ -22,6 +22,7 @@ import { AuthCollector } from './AuthCollector'
 import { EntitiesCollector } from './EntitiesCollector'
 import { RouterCollector } from './RouterCollector'
 import { I18nCollector } from './I18nCollector'
+import { RelayCollector, findRelayController } from '@quazardous/qddebug'
 import DebugBar from './components/DebugBar.vue'
 import type { KernelContext } from '../../kernel/KernelContext'
 
@@ -67,6 +68,8 @@ export interface DebugModuleOptions extends ModuleOptions {
   entitiesCollector?: boolean
   routerCollector?: boolean
   i18nCollector?: boolean
+  /** MCP tab (#2231) — only shown where the relay connector is installed */
+  relayCollector?: boolean
   _kernelManaged?: boolean
   /**
    * Existing DebugBridge to register collectors onto. When provided,
@@ -152,6 +155,12 @@ export class DebugModule extends Module {
       this._bridge.addCollector(new I18nCollector(collectorOptions))
     }
 
+    // The MCP tab (#2231), after i18n — and only where the app installed the
+    // relay connector: no connector, nothing to pair, no tab.
+    if (this.options.relayCollector !== false && findRelayController()) {
+      this._bridge.addCollector(new RelayCollector(collectorOptions))
+    }
+
     // Install collectors with context — only when WE own the bridge.
     // External bridges are installed by the host later with a merged
     // context that may include data from other frameworks (e.g. cms).

package/src/notifications/NotificationListener.vue

@@ -12,6 +12,7 @@ import { useToast } from 'primevue/usetoast'
 import type { SignalBus } from '../kernel/SignalBus'
 import { useNotifications } from './NotificationStore'
 import type { NotificationSeverity } from './NotificationStore'
+import { explainMissingToast } from '../kernel/vitePluginCheck'
 
 interface ToastEventData {
   summary?: string
@@ -21,7 +22,7 @@ interface ToastEventData {
   forceToast?: boolean
 }
 
-const toast = useToast()
+const toast = explainMissingToast(useToast)
 const signals = inject<SignalBus | null>('qdadmSignals', null)
 const store = useNotifications()
 

package/src/security/index.ts

@@ -69,6 +69,23 @@ export {
   type RoleListResult,
   type RoleInput,
 } from './RolesProviderStorage'
+export {
+  composeGrants,
+  inheritedGrants,
+  originOf,
+  setGrant,
+  type GrantDefinition,
+  type InheritedGrant,
+  type RoleComposition,
+  type InheritableRole,
+  type GrantOrigin,
+  type GrantCell,
+  type GrantRow,
+  type GrantGroup,
+  type OtherGrant,
+  type GrantsModel,
+  type RoleHierarchySource,
+} from './roleGrants'
 
 /**
  * Standard entity actions for CRUD operations