@open-mercato/shared 0.4.2-canary-c02407ff85

package/src/modules/entities/validators.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod'
+import { CUSTOM_FIELD_KINDS } from './kinds'
+import { validationRulesArraySchema } from './validation'
+
+export const entityIdRegex = /^[a-z0-9_]+:[a-z0-9_]+$/
+export const fieldsetCodeRegex = /^[a-z0-9_\-]+$/
+
+export const upsertCustomEntitySchema = z.object({
+  entityId: z.string().regex(
+    entityIdRegex,
+    'Enter the entity id in the format: module_name:entity_id with your prefered entity and module names'
+  ),
+  label: z.string().min(1).max(200),
+  description: z.string().max(2000).optional().nullable(),
+  labelField: z.string().min(1).max(100).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/).optional(),
+  defaultEditor: z.enum(['markdown','simpleMarkdown','htmlRichText']).optional(),
+  showInSidebar: z.boolean().default(false),
+  isActive: z.boolean().optional(),
+})
+
+export const upsertCustomFieldDefSchema = z.object({
+  entityId: z.string().regex(entityIdRegex),
+  key: z.string().min(1).max(100).regex(/^[a-z0-9_]+$/, 'snake_case only'),
+  kind: z.enum(CUSTOM_FIELD_KINDS),
+  configJson: z
+    .object({
+      // optional UI/behavioral hints
+      label: z.string().max(200).optional(),
+      description: z.string().max(2000).optional(),
+      options: z.array(z.union([z.string(), z.number()])).optional(),
+      optionsUrl: z.string().url().optional(),
+      multi: z.boolean().optional(),
+      editor: z.string().optional(),
+      input: z.string().optional(),
+      filterable: z.boolean().optional(),
+      formEditable: z.boolean().optional(),
+      listVisible: z.boolean().optional(),
+      priority: z.number().optional(),
+      encrypted: z.boolean().optional(),
+      relatedEntityId: z.string().optional(),
+      dictionaryId: z.string().uuid().optional(),
+      dictionaryInlineCreate: z.boolean().optional(),
+      // validation rules
+      validation: validationRulesArraySchema.optional(),
+      fieldset: z.string().regex(fieldsetCodeRegex).optional(),
+      group: z
+        .object({
+          code: z.string().regex(fieldsetCodeRegex),
+          title: z.string().max(200).optional(),
+          hint: z.string().max(500).optional(),
+        })
+        .optional(),
+    })
+    .passthrough()
+    .optional(),
+  isActive: z.boolean().optional(),
+})
+
+export const customFieldsetGroupSchema = z.object({
+  code: z.string().regex(fieldsetCodeRegex),
+  title: z.string().max(200).optional(),
+  hint: z.string().max(500).optional(),
+})
+
+export const customFieldsetSchema = z.object({
+  code: z.string().regex(fieldsetCodeRegex),
+  label: z.string().min(1).max(255),
+  icon: z.string().max(100).optional(),
+  description: z.string().max(2000).optional(),
+  groups: z.array(customFieldsetGroupSchema).optional(),
+})
+
+export const customFieldEntityConfigSchema = z.object({
+  fieldsets: z.array(customFieldsetSchema).max(20).optional(),
+  singleFieldsetPerRecord: z.boolean().optional(),
+})
+
+export const encryptionFieldRuleSchema = z.object({
+  field: z.string().min(1).max(200),
+  hashField: z.string().min(1).max(200).optional().nullable(),
+})
+
+export const upsertEncryptionMapSchema = z.object({
+  entityId: z.string().regex(entityIdRegex),
+  tenantId: z.string().uuid().nullable().optional(),
+  organizationId: z.string().uuid().nullable().optional(),
+  fields: z.array(encryptionFieldRuleSchema).min(1),
+  isActive: z.boolean().optional(),
+})
+
+export type UpsertCustomEntityInput = z.infer<typeof upsertCustomEntitySchema>
+export type UpsertCustomFieldDefInput = z.infer<typeof upsertCustomFieldDefSchema>
+export type UpsertEncryptionMapInput = z.infer<typeof upsertEncryptionMapSchema>

package/src/modules/entities.ts

@@ -0,0 +1,102 @@
+// Shared entity/extension/custom-field types used by generators and DI
+
+export type EntityId = string // format: '<module>:<entity>' e.g., 'auth:user'
+
+export type EntityExtension = {
+  // Base entity to extend, e.g., 'auth:user'
+  base: EntityId
+  // The extension entity that holds extra columns/relations, defined by the extending module
+  // Usually one-to-one keyed by base PK; other cardinalities allowed via explicit join keys
+  extension: EntityId
+  // Join description for query builder to link base <-> extension
+  join: {
+    baseKey: string // column name on base (e.g., 'id')
+    extensionKey: string // column name on extension (e.g., 'user_id')
+  }
+  cardinality?: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many'
+  required?: boolean
+  description?: string
+}
+
+export type CustomFieldKind =
+  | 'text'
+  | 'multiline'
+  | 'integer'
+  | 'float'
+  | 'boolean'
+  | 'select'
+  | 'currency'
+  | 'relation'
+  | 'attachment'
+  | 'dictionary'
+
+export type CustomFieldDefinition = {
+  id?: string // stable id; generated if omitted
+  key: string // unique within entity (snake_case)
+  kind: CustomFieldKind
+  label?: string
+  description?: string
+  fieldset?: string
+  group?: {
+    code: string
+    title?: string
+    hint?: string
+  }
+  required?: boolean
+  multi?: boolean // allow multiple values
+  options?: Array<
+    string | number | boolean | { value: string | number | boolean; label?: string | null }
+  >
+  // Optional dynamic options source for selects/tags relations
+  optionsUrl?: string
+  defaultValue?: string | number | boolean | null
+  filterable?: boolean
+  // whether field should be editable in generated CRUD forms
+  formEditable?: boolean
+  indexed?: boolean
+  listVisible?: boolean
+  // Optional UI hints for generated forms/filters
+  // Editors for multiline-rich text fields:
+  //  - 'markdown' -> UIW Markdown editor
+  //  - 'simpleMarkdown' -> minimal toolbar markdown
+  //  - 'htmlRichText' -> contenteditable rich text
+  editor?: 'markdown' | 'simpleMarkdown' | 'htmlRichText'
+  // Input hint for plain text fields (e.g., tags input when multi=true)
+  // Allow additional custom renderers (e.g., listbox from modules)
+  input?: string
+  // Relation helper metadata
+  relatedEntityId?: string
+  // Backed by global dictionaries module
+  dictionaryId?: string
+  dictionaryInlineCreate?: boolean
+  // Advanced validation rules applied in UI + API
+  validation?: Array<{ rule: string; param?: unknown; message?: string }>
+  // Attachments config passthrough (handled by attachments module)
+  maxAttachmentSizeMb?: number
+  acceptExtensions?: string[]
+}
+
+export type CustomFieldSet = {
+  entity: EntityId
+  fields: CustomFieldDefinition[]
+  // Optional: module id or other provenance
+  source?: string
+}
+
+export type EntityRegistrySpec = {
+  // Static, per-module declared extensions
+  extensions?: EntityExtension[]
+  // Static, per-module declared custom fields (seeded via migrations/CLI)
+  customFieldSets?: CustomFieldSet[]
+}
+
+export type CustomEntitySpec = {
+  id: EntityId
+  label?: string
+  description?: string
+  labelField?: string
+  defaultEditor?: string
+  showInSidebar?: boolean
+  global?: boolean
+  fields?: CustomFieldDefinition[]
+}

package/src/modules/navigation/sidebarPreferences.ts

@@ -0,0 +1,62 @@
+import { slugify } from '../../lib/slugify'
+
+export const SIDEBAR_PREFERENCES_VERSION = 2
+
+export type SidebarPreferencesSettings = {
+  version: number
+  groupOrder?: string[]
+  groupLabels?: Record<string, string>
+  itemLabels?: Record<string, string>
+  hiddenItems?: string[]
+}
+
+export type SidebarPreferencesPayload = {
+  locale: string
+  settings: SidebarPreferencesSettings
+}
+
+export function normalizeSidebarSettings(settings?: SidebarPreferencesSettings | null): SidebarPreferencesSettings {
+  if (!settings || typeof settings !== 'object') {
+    return { version: SIDEBAR_PREFERENCES_VERSION, groupOrder: [], groupLabels: {}, itemLabels: {}, hiddenItems: [] }
+  }
+  const version = typeof settings.version === 'number' ? settings.version : SIDEBAR_PREFERENCES_VERSION
+  const groupOrder = Array.isArray(settings.groupOrder) ? settings.groupOrder.filter((v): v is string => typeof v === 'string') : []
+  const groupLabels = normalizeRecord(settings.groupLabels)
+  const itemLabels = normalizeRecord(settings.itemLabels)
+  const hiddenItems = normalizeStringArray(settings.hiddenItems)
+  return {
+    version,
+    groupOrder,
+    groupLabels,
+    itemLabels,
+    hiddenItems,
+  }
+}
+
+function normalizeRecord(record: Record<string, unknown> | undefined): Record<string, string> {
+  if (!record || typeof record !== 'object') return {}
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value !== 'string') continue
+    out[key] = value
+  }
+  return out
+}
+
+function normalizeStringArray(values: unknown): string[] {
+  if (!Array.isArray(values)) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const value of values) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (!trimmed || seen.has(trimmed)) continue
+    seen.add(trimmed)
+    out.push(trimmed)
+  }
+  return out
+}
+
+export function slugifySidebarId(source: string): string {
+  return slugify(source, { allowedChars: '' }) || 'group'
+}

package/src/modules/perspectives/types.ts

@@ -0,0 +1,40 @@
+export type PerspectiveSettings = {
+  columnOrder?: string[]
+  columnVisibility?: Record<string, boolean>
+  filters?: Record<string, unknown>
+  sorting?: Array<{ id: string; desc?: boolean }>
+  pageSize?: number
+  searchValue?: string
+}
+
+export type PerspectiveDto = {
+  id: string
+  name: string
+  tableId: string
+  settings: PerspectiveSettings
+  isDefault: boolean
+  createdAt: string
+  updatedAt?: string | null
+}
+
+export type RolePerspectiveDto = PerspectiveDto & {
+  roleId: string
+  tenantId: string | null
+  organizationId: string | null
+  roleName?: string | null
+}
+
+export type PerspectivesIndexResponse = {
+  tableId: string
+  perspectives: PerspectiveDto[]
+  defaultPerspectiveId: string | null
+  rolePerspectives: RolePerspectiveDto[]
+  roles: Array<{ id: string; name: string; hasPerspective: boolean; hasDefault: boolean }>
+  canApplyToRoles: boolean
+}
+
+export type PerspectiveSaveResponse = {
+  perspective: PerspectiveDto
+  rolePerspectives: RolePerspectiveDto[]
+  clearedRoleIds: string[]
+}

package/src/modules/registry.ts

@@ -0,0 +1,249 @@
+import type { ReactNode } from 'react'
+import type { OpenApiRouteDoc, OpenApiMethodDoc } from '@open-mercato/shared/lib/openapi/types'
+import type { DashboardWidgetModule } from './dashboard/widgets'
+import type { InjectionWidgetModule, ModuleInjectionTable } from './widgets/injection'
+
+// Context passed to dynamic metadata guards
+export type RouteVisibilityContext = { path?: string; auth?: any }
+
+// Metadata you can export from page.meta.ts or directly from a server page
+export type PageMetadata = {
+  requireAuth?: boolean
+  requireRoles?: readonly string[]
+  // Optional fine-grained feature requirements
+  requireFeatures?: readonly string[]
+  // Titles and grouping (aliases supported)
+  title?: string
+  titleKey?: string
+  pageTitle?: string
+  pageTitleKey?: string
+  group?: string
+  groupKey?: string
+  pageGroup?: string
+  pageGroupKey?: string
+  // Ordering and visuals
+  order?: number
+  pageOrder?: number
+  icon?: ReactNode
+  navHidden?: boolean
+  // Dynamic flags
+  visible?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>
+  enabled?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>
+  // Optional static breadcrumb trail for header
+  breadcrumb?: Array<{ label: string; labelKey?: string; href?: string }>
+}
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+export type ApiHandler = (req: Request, ctx?: any) => Promise<Response> | Response
+
+export type ModuleRoute = {
+  pattern?: string
+  path?: string
+  requireAuth?: boolean
+  requireRoles?: string[]
+  // Optional fine-grained feature requirements
+  requireFeatures?: string[]
+  title?: string
+  titleKey?: string
+  group?: string
+  groupKey?: string
+  icon?: ReactNode
+  order?: number
+  priority?: number
+  navHidden?: boolean
+  visible?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>
+  enabled?: (ctx: RouteVisibilityContext) => boolean | Promise<boolean>
+  breadcrumb?: Array<{ label: string; labelKey?: string; href?: string }>
+  Component: (props: any) => ReactNode | Promise<ReactNode>
+}
+
+export type ModuleApiLegacy = {
+  method: HttpMethod
+  path: string
+  handler: ApiHandler
+  docs?: OpenApiMethodDoc
+}
+
+export type ModuleApiRouteFile = {
+  path: string
+  handlers: Partial<Record<HttpMethod, ApiHandler>>
+  requireAuth?: boolean
+  requireRoles?: string[]
+  // Optional fine-grained feature requirements for the entire route file
+  // Note: per-method feature requirements should be expressed inside metadata
+  requireFeatures?: string[]
+  docs?: OpenApiRouteDoc
+  metadata?: Partial<Record<HttpMethod, unknown>>
+}
+
+export type ModuleApi = ModuleApiLegacy | ModuleApiRouteFile
+
+export type ModuleCli = {
+  command: string
+  run: (argv: string[]) => Promise<void> | void
+}
+
+export type ModuleInfo = {
+  name?: string
+  title?: string
+  version?: string
+  description?: string
+  author?: string
+  license?: string
+  homepage?: string
+  copyright?: string
+  // Optional hard dependencies: module ids that must be enabled
+  requires?: string[]
+}
+
+export type ModuleDashboardWidgetEntry = {
+  moduleId: string
+  key: string
+  source: 'app' | 'package'
+  loader: () => Promise<DashboardWidgetModule<any>>
+}
+
+export type ModuleInjectionWidgetEntry = {
+  moduleId: string
+  key: string
+  source: 'app' | 'package'
+  loader: () => Promise<InjectionWidgetModule<any, any>>
+}
+
+export type Module = {
+  id: string
+  info?: ModuleInfo
+  backendRoutes?: ModuleRoute[]
+  frontendRoutes?: ModuleRoute[]
+  apis?: ModuleApi[]
+  cli?: ModuleCli[]
+  translations?: Record<string, Record<string, string>>
+  // Optional: per-module feature declarations discovered from acl.ts (module root)
+  features?: Array<{ id: string; title: string; module: string }>
+  // Auto-discovered event subscribers
+  subscribers?: Array<{
+    id: string
+    event: string
+    persistent?: boolean
+    // Imported function reference; will be registered into event bus
+    handler: (payload: any, ctx: any) => Promise<void> | void
+  }>
+  // Auto-discovered queue workers
+  workers?: Array<{
+    id: string
+    queue: string
+    concurrency: number
+    // Imported function reference; will be called by the queue worker
+    handler: (job: unknown, ctx: unknown) => Promise<void> | void
+  }>
+  // Optional: per-module declared entity extensions and custom fields (static)
+  // Extensions discovered from data/extensions.ts; Custom fields discovered from ce.ts (entities[].fields)
+  entityExtensions?: import('./entities').EntityExtension[]
+  customFieldSets?: import('./entities').CustomFieldSet[]
+  // Optional: per-module declared custom entities (virtual/logical entities)
+  // Discovered from ce.ts (module root). Each entry represents an entityId with optional label/description.
+  customEntities?: Array<{ id: string; label?: string; description?: string }>
+  dashboardWidgets?: ModuleDashboardWidgetEntry[]
+  injectionWidgets?: ModuleInjectionWidgetEntry[]
+  injectionTable?: ModuleInjectionTable
+}
+
+function normPath(s: string) {
+  return (s.startsWith('/') ? s : '/' + s).replace(/\/+$/, '') || '/'
+}
+
+function matchPattern(pattern: string, pathname: string): Record<string, string | string[]> | undefined {
+  const p = normPath(pattern)
+  const u = normPath(pathname)
+  const pSegs = p.split('/').slice(1)
+  const uSegs = u.split('/').slice(1)
+  const params: Record<string, string | string[]> = {}
+  let i = 0
+  for (let j = 0; j < pSegs.length; j++, i++) {
+    const seg = pSegs[j]
+    const mCatchAll = seg.match(/^\[\.\.\.(.+)\]$/)
+    const mOptCatch = seg.match(/^\[\[\.\.\.(.+)\]\]$/)
+    const mDyn = seg.match(/^\[(.+)\]$/)
+    if (mCatchAll) {
+      const key = mCatchAll[1]
+      if (i >= uSegs.length) return undefined
+      params[key] = uSegs.slice(i)
+      i = uSegs.length
+      return i === uSegs.length ? params : undefined
+    } else if (mOptCatch) {
+      const key = mOptCatch[1]
+      params[key] = i < uSegs.length ? uSegs.slice(i) : []
+      i = uSegs.length
+      return params
+    } else if (mDyn) {
+      if (i >= uSegs.length) return undefined
+      params[mDyn[1]] = uSegs[i]
+    } else {
+      if (i >= uSegs.length || uSegs[i] !== seg) return undefined
+    }
+  }
+  if (i !== uSegs.length) return undefined
+  return params
+}
+
+function getPattern(r: ModuleRoute) {
+  return r.pattern ?? r.path ?? '/'
+}
+
+export function findFrontendMatch(modules: Module[], pathname: string): { route: ModuleRoute; params: Record<string, string | string[]> } | undefined {
+  for (const m of modules) {
+    const routes = m.frontendRoutes ?? []
+    for (const r of routes) {
+      const params = matchPattern(getPattern(r), pathname)
+      if (params) return { route: r, params }
+    }
+  }
+}
+
+export function findBackendMatch(modules: Module[], pathname: string): { route: ModuleRoute; params: Record<string, string | string[]> } | undefined {
+  for (const m of modules) {
+    const routes = m.backendRoutes ?? []
+    for (const r of routes) {
+      const params = matchPattern(getPattern(r), pathname)
+      if (params) return { route: r, params }
+    }
+  }
+}
+
+export function findApi(modules: Module[], method: HttpMethod, pathname: string): { handler: ApiHandler; params: Record<string, string | string[]>; requireAuth?: boolean; requireRoles?: string[]; metadata?: any } | undefined {
+  for (const m of modules) {
+    const apis = m.apis ?? []
+    for (const a of apis) {
+      if ('handlers' in a) {
+        const params = matchPattern(a.path, pathname)
+        const handler = (a.handlers as any)[method]
+        if (params && handler) return { handler, params, requireAuth: a.requireAuth, requireRoles: (a as any).requireRoles, metadata: (a as any).metadata }
+      } else {
+        const al = a as ModuleApiLegacy
+        if (al.method === method && al.path === pathname) {
+          return { handler: al.handler, params: {} }
+        }
+      }
+    }
+  }
+}
+
+// CLI modules registry - shared between CLI and module workers
+let _cliModules: Module[] | null = null
+
+export function registerCliModules(modules: Module[]) {
+  if (_cliModules !== null && process.env.NODE_ENV === 'development') {
+    console.debug('[Bootstrap] CLI modules re-registered (this may occur during HMR)')
+  }
+  _cliModules = modules
+}
+
+export function getCliModules(): Module[] {
+  // Return empty array if not registered - allows generate command to work without bootstrap
+  return _cliModules ?? []
+}
+
+export function hasCliModules(): boolean {
+  return _cliModules !== null && _cliModules.length > 0
+}