@quazardous/qdadm 1.19.3

package/src/kernel/KernelContext.routing.ts

@@ -0,0 +1,280 @@
+/**
+ * Patch KernelContext prototype with routing-related methods:
+ *   - routes(basePath, routes, opts)
+ *   - navItem(item)
+ *   - routeFamily(base, prefixes)
+ *   - crud(entity, pages, options)             — convention CRUD generator
+ *   - childPage(parent, page, options)         — non-entity child route
+ *
+ * The string helpers (`singularize`, `toKebab`, `capitalize`) are kept
+ * module-local — they're pure, stateless, and were only used by `crud()` and
+ * `childPage()`. Keeping them off the prototype keeps the public shape clean.
+ */
+
+import type { RouteRecordRaw } from 'vue-router'
+import { registry, getRoutes } from '../module/moduleRegistry'
+import type {
+  ChildPageOptions,
+  CrudOptions,
+  CrudPages,
+  NavItem,
+  ParentConfig,
+  RouteOptions,
+} from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+/** Singularize a plural word (simple English rules) */
+function singularize(plural: string): string {
+  if (plural.endsWith('ies')) return plural.slice(0, -3) + 'y'
+  if (plural.endsWith('ses') || plural.endsWith('xes') || plural.endsWith('zes')) {
+    return plural.slice(0, -2)
+  }
+  if (plural.endsWith('s') && !plural.endsWith('ss')) return plural.slice(0, -1)
+  return plural
+}
+
+/** Convert camelCase to kebab-case (e.g. 'botTasks' → 'bot-tasks') */
+function toKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+/** Capitalize first letter */
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyRoutingMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  proto.routes = function (
+    this: Self,
+    basePath: string,
+    routes: RouteRecordRaw[],
+    opts: RouteOptions = {}
+  ): Self {
+    registry.addRoutes(basePath, routes, opts)
+    return this
+  }
+
+  proto.navItem = function (this: Self, item: NavItem): Self {
+    registry.addNavItem(item)
+    return this
+  }
+
+  proto.routeFamily = function (this: Self, base: string, prefixes: string[]): Self {
+    registry.addRouteFamily(base, prefixes)
+    return this
+  }
+
+  /**
+   * Register standard CRUD routes with naming conventions
+   * (entity 'books' → route prefix 'book', /books → 'book', etc.)
+   */
+  proto.crud = function (
+    this: Self,
+    entity: string,
+    pages: CrudPages,
+    options: CrudOptions = {}
+  ): Self {
+    // Entity name is always used for permission binding.
+    // Manager may not be registered yet (child entity before parent module loads).
+    const entityBinding = entity
+    const manager = this._kernel.orchestrator?.isRegistered(entity)
+      ? this._kernel.orchestrator.get(entity)
+      : null
+    const idParam = manager?.idField || 'id'
+
+    // Handle parent route configuration
+    const urlSegment = options.pathSegment || toKebab(entity)
+    let basePath = urlSegment
+    let parentConfig: ParentConfig | null = null
+    let parentRoutePrefix: string | null = null
+
+    if (options.parentRoute) {
+      const parentRouteName = options.parentRoute
+      const allRoutes = getRoutes()
+      const parentRoute = allRoutes.find((r) => r.name === parentRouteName)
+
+      if (parentRoute) {
+        const parentEntityName = parentRoute.meta?.entity
+        const parentManager = parentEntityName
+          ? this._kernel.orchestrator?.get(parentEntityName)
+          : null
+        const parentIdParam = parentManager?.idField || 'id'
+
+        // Build base path: parentPath/:parentId/entity (e.g., books/:bookId/loans)
+        const parentBasePath =
+          parentRoute.path.replace(/\/(create|:.*)?$/, '') || parentEntityName
+        basePath = `${parentBasePath}/:${parentIdParam}/${urlSegment}`
+
+        if (parentEntityName) {
+          parentConfig = {
+            entity: parentEntityName,
+            param: parentIdParam,
+            foreignKey: options.foreignKey || `${singularize(parentEntityName)}_id`,
+          }
+        }
+
+        parentRoutePrefix = parentRouteName
+      }
+    }
+
+    // Derive route prefix:
+    //   With parent:    'book' + '-loan' → 'book-loan'
+    //   Without parent: 'books' → 'book'
+    const routePrefix =
+      options.routePrefix ||
+      (parentRoutePrefix
+        ? `${parentRoutePrefix}-${singularize(entity)}`
+        : singularize(entity))
+
+    const routes: RouteRecordRaw[] = []
+
+    if (pages.list) {
+      routes.push({
+        path: '',
+        name: routePrefix,
+        component: pages.list,
+        meta: { layout: 'list' },
+      })
+    }
+
+    if (pages.show) {
+      routes.push({
+        path: `:${idParam}`,
+        name: `${routePrefix}-show`,
+        component: pages.show,
+        meta: { layout: 'show' },
+      })
+    }
+
+    if (pages.form) {
+      // Single form pattern (recommended)
+      routes.push({
+        path: 'create',
+        name: `${routePrefix}-create`,
+        component: pages.form,
+      })
+      routes.push({
+        path: `:${idParam}/edit`,
+        name: `${routePrefix}-edit`,
+        component: pages.form,
+      })
+    } else {
+      if (pages.create) {
+        routes.push({
+          path: 'create',
+          name: `${routePrefix}-create`,
+          component: pages.create,
+        })
+      }
+      if (pages.edit) {
+        routes.push({
+          path: `:${idParam}/edit`,
+          name: `${routePrefix}-edit`,
+          component: pages.edit,
+        })
+      }
+    }
+
+    const routeOpts: RouteOptions = {}
+    // Set entity if registered, OR if this is a child route — child routes
+    // need entity binding for permission checks even before the manager
+    // exists.
+    if (manager || parentConfig) {
+      routeOpts.entity = entityBinding
+    }
+    if (parentConfig) {
+      routeOpts.parent = parentConfig
+    }
+    if (options.label) {
+      routeOpts.label = options.label
+    }
+
+    this.routes(basePath, routes, routeOpts)
+    this.routeFamily(routePrefix, [`${routePrefix}-`])
+
+    if (options.nav) {
+      const label = options.nav.label || capitalize(entity)
+      const navItem: NavItem = {
+        section: options.nav.section,
+        route: routePrefix,
+        icon: options.nav.icon,
+        label,
+      }
+      // Only set entity on nav item if registered (avoids permission check
+      // failure). Routes always get entity binding, but nav items need it
+      // resolvable.
+      if (manager) {
+        navItem.entity = entityBinding
+      }
+      this.navItem(navItem)
+    }
+
+    return this
+  }
+
+  /**
+   * Register a custom child page on an entity item (e.g. /books/:id/statistics).
+   */
+  proto.childPage = function (
+    this: Self,
+    parentRouteName: string,
+    pageName: string,
+    options: ChildPageOptions
+  ): Self {
+    const allRoutes = getRoutes()
+    const parentRoute = allRoutes.find((r) => r.name === parentRouteName)
+
+    if (!parentRoute) {
+      console.warn(`[qdadm] childPage: parent route '${parentRouteName}' not found`)
+      return this
+    }
+
+    const parentEntityName = parentRoute.meta?.entity as string | undefined
+    const parentManager = parentEntityName
+      ? this._kernel.orchestrator?.get(parentEntityName)
+      : null
+    const parentIdParam = parentManager?.idField || 'id'
+
+    const parentBasePath =
+      parentRoute.path.replace(/\/(create|:.*)?$/, '') || parentEntityName
+    const basePath = `${parentBasePath}/:${parentIdParam}/${pageName}`
+
+    const routeName = `${parentRouteName}-${pageName}`
+
+    const parentConfig: ParentConfig | undefined = parentEntityName
+      ? { entity: parentEntityName, param: parentIdParam }
+      : undefined
+
+    const routeOpts: RouteOptions = {}
+    if (parentConfig) {
+      routeOpts.parent = parentConfig
+    }
+    if (options.label) {
+      routeOpts.label = options.label
+    }
+
+    this.routes(
+      basePath,
+      [
+        {
+          path: '',
+          name: routeName,
+          component: options.component,
+          meta: {
+            layout: 'page',
+            ...(options.icon && { icon: options.icon }),
+            ...options.meta,
+          },
+        },
+      ],
+      routeOpts
+    )
+
+    return this
+  }
+}

package/src/kernel/KernelContext.ts

@@ -0,0 +1,252 @@
+/**
+ * KernelContext - Fluent API wrapper for module registration.
+ *
+ * Provides a chainable interface for modules to register entities, routes,
+ * navigation items, zones, blocks, signal handlers, hooks, permissions and
+ * translations.
+ *
+ * The class shell here keeps the constructor + service getters; the fluent
+ * registration methods live in dedicated patch modules following the same
+ * pattern as `Kernel.ts`:
+ *
+ *   - KernelContext.entities.ts    — entity, userEntity
+ *   - KernelContext.routing.ts     — routes, navItem, routeFamily, crud, childPage
+ *   - KernelContext.zones.ts       — zone, block, provide, component
+ *   - KernelContext.events.ts      — on, hook, defer
+ *   - KernelContext.permissions.ts — permissions, entityPermissions
+ *   - KernelContext.i18n.ts        — messages, aliases, messagesProvider
+ *
+ * Usage in a module:
+ * ```ts
+ * class UsersModule extends Module {
+ *   async connect(ctx: KernelContext) {
+ *     ctx
+ *       .entity('users', { storage: 'api:/api/users' })
+ *       .routes('users', [
+ *         { path: '', name: 'users', component: UserList },
+ *         { path: ':id', name: 'users-edit', component: UserEdit }
+ *       ])
+ *       .navItem({ section: 'Admin', route: 'users', icon: 'pi pi-users', label: 'Users' })
+ *       .zone('users-list-header')
+ *       .block('users-list-header', { component: UserStats, weight: 10 })
+ *       .on('users:created', (event) => console.log('User created:', event))
+ *   }
+ * }
+ * ```
+ */
+
+import type { App, Component } from 'vue'
+import type { Router, RouteRecordRaw } from 'vue-router'
+import type { ListenerOptions } from '@quazardous/quarkernel'
+import type { SignalBus } from './SignalBus'
+import type { Orchestrator } from '../orchestrator/Orchestrator'
+import type { HookRegistry } from '../hooks/HookRegistry'
+import type { ZoneRegistry } from '../zones/ZoneRegistry'
+import type { DeferredRegistry } from '../deferred/DeferredRegistry.js'
+import type { SecurityChecker } from '../entity/auth/SecurityChecker'
+import type { PermissionRegistry } from '../security/PermissionRegistry'
+import type { EntityManager } from '../entity/EntityManager'
+import type { I18n } from '../i18n/I18n'
+import type { AliasPattern, MessagesBundle, TranslationProvider } from '../i18n/types'
+
+// Internal types (shared with patch modules, not exported here).
+import type {
+  AuthAdapter,
+  DeferredFactory,
+  HookHandler,
+  KernelInterface,
+  ModuleWithCleanup,
+  SignalHandler,
+} from './KernelContext.types'
+
+// Public types — re-exported to keep the existing barrel API stable.
+export type {
+  BlockConfig,
+  ChildPageOptions,
+  CrudOptions,
+  CrudPages,
+  NavItem,
+  ParentConfig,
+  PermissionMeta,
+  PermissionOptions,
+  RouteOptions,
+  UserEntityOptions,
+  ZoneOptions,
+} from './KernelContext.types'
+import type {
+  BlockConfig,
+  ChildPageOptions,
+  CrudOptions,
+  CrudPages,
+  NavItem,
+  PermissionMeta,
+  PermissionOptions,
+  RouteOptions,
+  UserEntityOptions,
+  ZoneOptions,
+} from './KernelContext.types'
+
+// Prototype-patched method groups
+import { applyEntityMethods } from './KernelContext.entities'
+import { applyRoutingMethods } from './KernelContext.routing'
+import { applyZoneMethods } from './KernelContext.zones'
+import { applyEventMethods } from './KernelContext.events'
+import { applyPermissionMethods } from './KernelContext.permissions'
+import { applyI18nMethods } from './KernelContext.i18n'
+
+export class KernelContext {
+  // Marked public so the patch modules (which read this.* via Self=any) can
+  // see them. They were `private` in the previous monolithic file but were
+  // already accessed across patch boundaries the moment we split.
+  _kernel: KernelInterface
+  _module: ModuleWithCleanup | null
+
+  constructor(kernel: KernelInterface, module: ModuleWithCleanup | null) {
+    this._kernel = kernel
+    this._module = module
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Getters for kernel services
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** Vue app instance */
+  get app(): App | null {
+    return this._kernel.vueApp
+  }
+
+  /** Vue router instance */
+  get router(): Router | null {
+    return this._kernel.router
+  }
+
+  /** SignalBus instance */
+  get signals(): SignalBus | null {
+    return this._kernel.signals
+  }
+
+  /** Orchestrator instance (entity managers) */
+  get orchestrator(): Orchestrator | null {
+    return this._kernel.orchestrator
+  }
+
+  /** ZoneRegistry instance */
+  get zones(): ZoneRegistry | null {
+    return this._kernel.zoneRegistry
+  }
+
+  /** HookRegistry instance */
+  get hooks(): HookRegistry | null {
+    return this._kernel.hookRegistry
+  }
+
+  /** DeferredRegistry instance */
+  get deferred(): DeferredRegistry | null {
+    return this._kernel.deferred
+  }
+
+  /** Whether running in development mode */
+  get isDev(): boolean {
+    return (import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV ?? false
+  }
+
+  /** Debug mode from kernel options */
+  get debug(): boolean {
+    return this._kernel.options?.debug ?? false
+  }
+
+  /** Auth adapter */
+  get authAdapter(): AuthAdapter | null {
+    return this._kernel.options?.authAdapter ?? null
+  }
+
+  /** Security checker (role hierarchy, permissions) */
+  get security(): SecurityChecker | null {
+    return this._kernel.securityChecker
+  }
+
+  /** Permission registry */
+  get permissionRegistry(): PermissionRegistry | null {
+    return this._kernel.permissionRegistry
+  }
+
+  /** Auth adapter shortcut */
+  get auth(): AuthAdapter | null {
+    return this._kernel.options?.authAdapter ?? null
+  }
+
+  /** ActiveStack instance (sync navigation context) */
+  get activeStack(): unknown {
+    return this._kernel.activeStack ?? null
+  }
+
+  /** StackHydrator instance (async data loading) */
+  get stackHydrator(): unknown {
+    return this._kernel.stackHydrator ?? null
+  }
+
+  /** I18n subsystem */
+  get i18n(): I18n | null {
+    return this._kernel.i18nInstance ?? null
+  }
+}
+
+// Declare prototype-patched methods (declaration merging)
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface KernelContext {
+  // Entities (KernelContext.entities.ts)
+  entity(name: string, config: string | Record<string, unknown> | EntityManager): this
+  userEntity(options: UserEntityOptions): this
+
+  // Routing (KernelContext.routing.ts)
+  routes(basePath: string, routes: RouteRecordRaw[], opts?: RouteOptions): this
+  navItem(item: NavItem): this
+  routeFamily(base: string, prefixes: string[]): this
+  crud(entity: string, pages: CrudPages, options?: CrudOptions): this
+  childPage(parentRouteName: string, pageName: string, options: ChildPageOptions): this
+
+  // Zones / Vue (KernelContext.zones.ts)
+  zone(name: string, options?: ZoneOptions): this
+  block(zoneName: string, config: BlockConfig): this
+  provide(key: string | symbol, value: unknown): this
+  component(name: string, component: Component): this
+
+  // Events (KernelContext.events.ts)
+  on(signal: string, handler: SignalHandler, options?: ListenerOptions): this
+  hook(hookName: string, handler: HookHandler, options?: Record<string, unknown>): this
+  defer(name: string, factory: DeferredFactory): this
+
+  // Permissions (KernelContext.permissions.ts)
+  permissions(
+    namespace: string,
+    permissions: Record<string, string | PermissionMeta>,
+    options?: PermissionOptions
+  ): this
+  entityPermissions(
+    entity: string,
+    permissions: Record<string, string | PermissionMeta>
+  ): this
+
+  // i18n (KernelContext.i18n.ts)
+  messages(locale: string, bundle: MessagesBundle): this
+  aliases(patterns: AliasPattern[]): this
+  messagesProvider(provider: TranslationProvider): this
+}
+
+// Apply prototype patches
+applyEntityMethods(KernelContext)
+applyRoutingMethods(KernelContext)
+applyZoneMethods(KernelContext)
+applyEventMethods(KernelContext)
+applyPermissionMethods(KernelContext)
+applyI18nMethods(KernelContext)
+
+/**
+ * Factory function to create a KernelContext instance.
+ */
+export function createKernelContext(
+  kernel: KernelInterface,
+  module: ModuleWithCleanup | null
+): KernelContext {
+  return new KernelContext(kernel, module)
+}

package/src/kernel/KernelContext.types.ts

@@ -0,0 +1,173 @@
+/**
+ * KernelContext types - shared between the class shell and the prototype-patch
+ * modules (KernelContext.{entities,routing,zones,events,permissions,i18n}.ts).
+ *
+ * Internal types (ModuleWithCleanup, AuthAdapter, KernelOptions,
+ * KernelInterface, function types) stay un-exported by KernelContext.ts so
+ * they remain private to qdadm internals; the public types (NavItem,
+ * ZoneOptions, …) are re-exported from KernelContext.ts to preserve the
+ * existing barrel API.
+ */
+
+import type { App, Component } from 'vue'
+import type { Router } from 'vue-router'
+import type { UsersManagerOptions } from '../security/UsersManager'
+import type { SignalBus } from './SignalBus'
+import type { Orchestrator } from '../orchestrator/Orchestrator'
+import type { HookRegistry } from '../hooks/HookRegistry'
+import type { ZoneRegistry } from '../zones/ZoneRegistry'
+import type { DeferredRegistry } from '../deferred/DeferredRegistry.js'
+import type { SecurityChecker } from '../entity/auth/SecurityChecker'
+import type { PermissionRegistry } from '../security/PermissionRegistry'
+import type { I18n } from '../i18n/I18n'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal types — shared across patch modules, not exposed by index.ts
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Extended Module interface with internal cleanup method */
+export interface ModuleWithCleanup {
+  constructor?: { name?: string }
+  _addSignalCleanup?: (cleanup: () => void) => void
+}
+
+/** Auth adapter interface */
+export interface AuthAdapter {
+  getUser(): unknown
+  [key: string]: unknown
+}
+
+/** Kernel options interface */
+export interface KernelOptions {
+  debug?: boolean
+  authAdapter?: AuthAdapter | null
+  storageResolver?: unknown
+  managerResolver?: unknown
+  managerRegistry?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/** Kernel interface for type safety inside KernelContext */
+export interface KernelInterface {
+  vueApp: App | null
+  router: Router | null
+  signals: SignalBus | null
+  orchestrator: Orchestrator | null
+  zoneRegistry: ZoneRegistry | null
+  hookRegistry: HookRegistry | null
+  deferred: DeferredRegistry | null
+  securityChecker: SecurityChecker | null
+  permissionRegistry: PermissionRegistry | null
+  activeStack: unknown
+  stackHydrator: unknown
+  options: KernelOptions
+  i18nInstance: I18n | null
+  _pendingProvides: Map<string | symbol, unknown>
+  _pendingComponents: Map<string, Component>
+}
+
+/** Signal handler function type */
+export type SignalHandler = (event: { data: unknown; [key: string]: unknown }) => void
+
+/** Hook handler function type */
+export type HookHandler = (context: unknown) => unknown | Promise<unknown>
+
+/** Deferred factory function type */
+export type DeferredFactory = () => Promise<void>
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public types — re-exported by KernelContext.ts (and ultimately by index.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Navigation item configuration */
+export interface NavItem {
+  section: string
+  route: string
+  label: string
+  icon?: string
+  exact?: boolean
+  entity?: string
+}
+
+/** Zone configuration */
+export interface ZoneOptions {
+  default?: Component
+}
+
+/** Block configuration */
+export interface BlockConfig {
+  component: Component
+  weight?: number
+  props?: Record<string, unknown>
+  id?: string
+  operation?: 'add' | 'replace' | 'extend' | 'wrap'
+  /** Block ID to replace (required if operation='replace') */
+  replaces?: string
+  /** Block ID to insert before (for operation='extend') */
+  before?: string
+  /** Block ID to insert after (for operation='extend') */
+  after?: string
+  /** Block ID to wrap (required if operation='wrap') */
+  wraps?: string
+}
+
+/** Route options */
+export interface RouteOptions {
+  entity?: string
+  parent?: ParentConfig
+  label?: string
+  layout?: string
+}
+
+/** Parent route configuration */
+export interface ParentConfig {
+  entity: string
+  param: string
+  foreignKey?: string
+}
+
+/** CRUD page components */
+export interface CrudPages {
+  list?: () => Promise<{ default: Component }>
+  show?: () => Promise<{ default: Component }>
+  form?: () => Promise<{ default: Component }>
+  create?: () => Promise<{ default: Component }>
+  edit?: () => Promise<{ default: Component }>
+}
+
+/** CRUD options */
+export interface CrudOptions {
+  nav?: {
+    section: string
+    icon?: string
+    label?: string
+  }
+  routePrefix?: string
+  /** Override the URL path segment (defaults to entity name). Useful for camelCase entities like 'jobTasks' → 'tasks'. */
+  pathSegment?: string
+  parentRoute?: string
+  foreignKey?: string
+  label?: string
+}
+
+/** Child page options for non-entity child routes */
+export interface ChildPageOptions {
+  component: () => Promise<{ default: Component }>
+  label?: string
+  icon?: string
+  meta?: Record<string, unknown>
+}
+
+/** User entity options */
+export type UserEntityOptions = UsersManagerOptions
+
+/** Permission metadata */
+export interface PermissionMeta {
+  label: string
+  description?: string
+}
+
+/** Permission options */
+export interface PermissionOptions {
+  isEntity?: boolean
+}