@nextsparkjs/core 0.1.0-beta.13 → 0.1.0-beta.131

package/scripts/build/registry/generators/docs-registry.mjs

@@ -0,0 +1,241 @@
+/**
+ * Docs Registry Generator
+ *
+ * Generates docs-registry.ts with actual documentation content.
+ * Scans themes/{THEME}/docs/public/ and docs/superadmin/ directories.
+ *
+ * @module core/scripts/build/registry/generators/docs-registry
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { existsSync } from 'fs'
+import { CONFIG } from '../config.mjs'
+
+// Get config values - use themesDir which correctly handles monorepo mode
+const projectRoot = CONFIG.projectRoot
+const monorepoRoot = CONFIG.monorepoRoot
+const isNpmMode = CONFIG.isNpmMode
+const isMonorepoMode = CONFIG.isMonorepoMode
+
+// Themes directory - use CONFIG.themesDir for correct monorepo/npm mode handling
+const THEMES_DIR = CONFIG.themesDir
+
+/**
+ * Extract order number from filename (01-example -> 1)
+ */
+function extractOrder(name) {
+  const match = name.match(/^(\d+)-/)
+  return match ? parseInt(match[1], 10) : 999
+}
+
+/**
+ * Clean filename (01-example.md -> example)
+ */
+function cleanName(name) {
+  return name.replace(/^\d+-/, '').replace(/\.md$/, '')
+}
+
+/**
+ * Convert slug to title (getting-started -> Getting Started)
+ */
+function slugToTitle(slug) {
+  return slug
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Scan a documentation directory and build registry metadata
+ *
+ * @param {string} docsPath - Absolute path to docs directory
+ * @param {'public' | 'superadmin'} source - Source type
+ * @returns {Array} Array of section metadata
+ */
+function scanDocsDirectory(docsPath, source) {
+  if (!existsSync(docsPath)) {
+    return []
+  }
+
+  const sections = []
+  const items = fs.readdirSync(docsPath, { withFileTypes: true })
+
+  for (const item of items) {
+    if (!item.isDirectory()) continue
+
+    const sectionPath = path.join(docsPath, item.name)
+    const order = extractOrder(item.name)
+    const slug = cleanName(item.name)
+    const title = slugToTitle(slug)
+
+    const pages = []
+    const files = fs.readdirSync(sectionPath)
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue
+
+      const filePath = path.join(sectionPath, file)
+      const fileOrder = extractOrder(file)
+      const pageSlug = cleanName(file)
+      const pageTitle = slugToTitle(pageSlug)
+
+      // Get relative path from consuming app directory
+      // In monorepo mode: calculate relative from projectRoot (apps/dev) to file in themes/
+      // In npm mode: calculate relative from projectRoot to file in contents/themes/
+      let relativePath
+      if (isMonorepoMode && monorepoRoot) {
+        // In monorepo, themes are at monorepoRoot/themes/
+        // projectRoot is apps/dev, so we need ../../themes/...
+        const themeRelativePath = filePath.replace(monorepoRoot, '')
+        relativePath = '../..' + themeRelativePath
+      } else {
+        // In npm mode, themes are at projectRoot/contents/themes/
+        relativePath = filePath.replace(projectRoot, '')
+      }
+
+      pages.push({
+        slug: pageSlug,
+        title: pageTitle,
+        order: fileOrder,
+        path: relativePath,
+        source
+      })
+    }
+
+    // Sort pages by order
+    pages.sort((a, b) => a.order - b.order)
+
+    sections.push({
+      title,
+      slug,
+      order,
+      pages,
+      source
+    })
+  }
+
+  // Sort sections by order
+  return sections.sort((a, b) => a.order - b.order)
+}
+
+/**
+ * Generate the docs registry file with actual content
+ *
+ * @returns {string} Generated TypeScript content
+ */
+export function generateDocsRegistry() {
+  const theme = CONFIG.activeTheme || 'default'
+  const themeDocsDir = path.join(THEMES_DIR, theme, 'docs')
+
+  // Scan public docs (user-facing → /docs)
+  const publicDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'public'),
+    'public'
+  )
+
+  // Scan superadmin docs (admin-facing → /superadmin/docs)
+  const superadminDocs = scanDocsDirectory(
+    path.join(themeDocsDir, 'superadmin'),
+    'superadmin'
+  )
+
+  // Create registry
+  const registry = {
+    public: publicDocs,
+    superadmin: superadminDocs,
+    all: [...publicDocs, ...superadminDocs].sort((a, b) => a.order - b.order)
+  }
+
+  // Total pages count
+  const publicPages = publicDocs.reduce((sum, section) => sum + section.pages.length, 0)
+  const superadminPages = superadminDocs.reduce((sum, section) => sum + section.pages.length, 0)
+  const totalPages = publicPages + superadminPages
+
+  return `/**
+ * Auto-generated Documentation Registry
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Theme: ${theme}
+ * Public sections: ${publicDocs.length}
+ * Superadmin sections: ${superadminDocs.length}
+ * Total pages: ${totalPages}
+ *
+ * Structure:
+ * - public: User-facing documentation → /docs
+ * - superadmin: Admin documentation → /superadmin/docs
+ *
+ * DO NOT EDIT - This file is auto-generated
+ */
+
+// Inline type definitions for npm mode (avoids import issues since DTS is disabled)
+export interface DocPageMeta {
+  slug: string
+  title: string
+  order: number
+  path: string
+  source: 'public' | 'superadmin'
+}
+
+export interface DocSectionMeta {
+  slug: string
+  title: string
+  order: number
+  pages: DocPageMeta[]
+  source: 'public' | 'superadmin'
+}
+
+export interface DocsRegistryStructure {
+  public: DocSectionMeta[]
+  superadmin: DocSectionMeta[]
+  all: DocSectionMeta[]
+}
+
+export const DOCS_REGISTRY: DocsRegistryStructure = ${JSON.stringify(registry, null, 2)} as const
+
+export type DocsRegistry = typeof DOCS_REGISTRY
+
+/**
+ * Get all documentation sections (public + superadmin)
+ */
+export function getAllDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.all
+}
+
+/**
+ * Get public documentation sections only (for /docs)
+ */
+export function getPublicDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.public
+}
+
+/**
+ * Get superadmin documentation sections only (for /superadmin/docs)
+ */
+export function getSuperadminDocSections(): DocSectionMeta[] {
+  return DOCS_REGISTRY.superadmin
+}
+
+/**
+ * Find a section by slug
+ */
+export function findDocSection(slug: string): DocSectionMeta | undefined {
+  return DOCS_REGISTRY.all.find(section => section.slug === slug)
+}
+
+/**
+ * Find a section by slug in a specific category
+ */
+export function findDocSectionInCategory(slug: string, category: 'public' | 'superadmin'): DocSectionMeta | undefined {
+  return DOCS_REGISTRY[category].find(section => section.slug === slug)
+}
+
+/**
+ * Find a page within a section
+ */
+export function findDocPage(sectionSlug: string, pageSlug: string): DocPageMeta | undefined {
+  const section = findDocSection(sectionSlug)
+  return section?.pages.find(page => page.slug === pageSlug)
+}
+`
+}

package/scripts/build/registry/generators/entity-registry.mjs

@@ -18,9 +18,14 @@ import { convertCorePath } from '../config.mjs'
  */
 export function generateEntityRegistry(entities, config) {
   const outputFilePath = join(config.outputDir, 'entity-registry.ts')
-  const imports = entities.map(entity =>
-    `import { ${entity.exportName} } from '${entity.configPath}'`
-  ).join('\n')
+  const imports = entities.map(entity => {
+    // Strip .ts extension if present - Next.js resolves extensions automatically on all platforms
+    let configPath = entity.configPath
+    if (configPath.endsWith('.ts')) {
+      configPath = configPath.slice(0, -3)
+    }
+    return `import { ${entity.exportName} } from '${configPath}'`
+  }).join('\n')
 
   const registryEntries = entities.map(entity => {
     // NEW STRUCTURE: Derive table name from slug automatically
@@ -137,9 +142,14 @@ export function generateEntityRegistryClient(entities, config) {
   const entityNames = entities.map(e => `'${e.name}'`).join(' | ')
 
   // Import entity configurations to extract client-safe properties
-  const imports = entities.map(entity =>
-    `import { ${entity.exportName} } from '${entity.configPath}'`
-  ).join('\n')
+  const imports = entities.map(entity => {
+    // Strip .ts extension if present - Next.js resolves extensions automatically on all platforms
+    let configPath = entity.configPath
+    if (configPath.endsWith('.ts')) {
+      configPath = configPath.slice(0, -3)
+    }
+    return `import { ${entity.exportName} } from '${configPath}'`
+  }).join('\n')
 
   const clientRegistryEntries = entities.map(entity => {
     // Use dynamic reference to extract client-safe properties from imported config
@@ -185,6 +195,8 @@ export function generateEntityRegistryClient(entities, config) {
     builder: ${entity.exportName}.builder ? {
       enabled: ${entity.exportName}.builder.enabled,
       sidebarFields: ${entity.exportName}.builder.sidebarFields,
+      sidebarFieldsConfig: ${entity.exportName}.builder.sidebarFieldsConfig,
+      showSlug: ${entity.exportName}.builder.showSlug,
       public: ${entity.exportName}.builder.public,
       seo: ${entity.exportName}.builder.seo
     } : undefined,
@@ -201,7 +213,15 @@ export function generateEntityRegistryClient(entities, config) {
     return `      '${slug}': '${entity.name}'`
   }).join(',\n')
 
-  return `/**
+  // Generate icon registration calls
+  const iconRegistrations = entities
+    .filter(entity => entity.exportName)
+    .map(entity => `registerEntityIcon('${entity.name}', ${entity.exportName}.icon)`)
+    .join('\n')
+
+  return `'use client'
+
+/**
  * Client-Safe Entity Registry
  *
  * Generated at: ${new Date().toISOString()}
@@ -215,6 +235,10 @@ export function generateEntityRegistryClient(entities, config) {
  */
 
 ${imports}
+import { registerEntityIcon } from '${convertCorePath('@/core/lib/entities/registry.client', outputFilePath, config)}'
+
+// Pre-register entity icons so non-lucide icons survive server→client serialization
+${iconRegistrations}
 
 export interface ClientEntityConfig {
   name: string
@@ -249,6 +273,17 @@ export interface ClientEntityConfig {
   builder?: {
     enabled: boolean
     sidebarFields?: string[]
+    sidebarFieldsConfig?: Array<{
+      name: string
+      type: string
+      label?: string
+      placeholder?: string
+      rows?: number
+      relation?: { entity: string; titleField: string; userFiltered?: boolean; limit?: number; filter?: Record<string, string> }
+      options?: Array<{ value: string; label: string }>
+      conditionalOn?: { field: string; value: string | string[] }
+    }>
+    showSlug?: boolean
     public?: { basePath: string }
     seo?: boolean
   }

package/scripts/build/registry/generators/index.mjs

@@ -22,4 +22,5 @@ export { generatePermissionsRegistry } from './permissions-registry.mjs'
 export { generateEntityTypes } from './entity-types.mjs'
 export { generateAuthRegistry } from './auth-registry.mjs'
 export { generateUnifiedRegistry } from './unified-registry.mjs'
-export { generateFeatureRegistry, generateFeatureRegistryFull, generateTagsRegistryJson } from './feature-registry.mjs'
+export { generateFeatureRegistry, generateFeatureRegistryFull } from './feature-registry.mjs'
+export { generateApiPresetsRegistry, generateApiDocsRegistry } from './api-presets-registry.mjs'

package/scripts/build/registry/generators/namespace-registry.mjs

@@ -15,7 +15,7 @@
  */
 export function generateNamespaceRegistry(entities, config) {
   // Core namespaces (always available)
-  const coreNamespaces = ['common', 'dashboard', 'settings', 'auth', 'public', 'validation', 'superadmin']
+  const coreNamespaces = ['common', 'dashboard', 'settings', 'auth', 'public', 'validation', 'superadmin', 'admin', 'teams']
 
   // Entity namespaces (generated from entities)
   const entityNamespaces = entities
@@ -25,7 +25,7 @@ export function generateNamespaceRegistry(entities, config) {
   // Route-based namespace mappings
   const routeNamespaces = {
     'DASHBOARD_AUTHENTICATED': {
-      core: ['common', 'dashboard', 'settings', 'public', 'validation'],
+      core: ['common', 'dashboard', 'settings', 'public', 'validation', 'teams', 'admin'],
       entities: entityNamespaces,
       strategy: 'DASHBOARD_AUTHENTICATED'
     },

package/scripts/build/registry/generators/permissions-registry.mjs

@@ -48,10 +48,73 @@ export async function generatePermissionsRegistry(permissionsConfig, entities, c
   const entityPermissions = []
   const processedEntities = new Set()
 
+  // Build a Set of all known entity slugs for validation
+  // Entities come from theme + plugins, use 'name' which matches directory/slug
+  const knownEntitySlugs = new Set(entities.map(e => e.name))
+
   // PRIORITY 1: Read from permissions.config.ts -> entities (centralized definition)
   // This allows custom roles like 'editor' to be included directly in roles
   if (hasThemeConfig && permissionsConfig.entities) {
     log('  📋 Reading entity permissions from permissions.config.ts (centralized)', 'info')
+
+    // =========================================================================
+    // VALIDATION: Ensure all entity keys in permissions.config.ts match
+    // discovered entity slugs. This prevents runtime permission resolution bugs.
+    // =========================================================================
+    const permissionEntityKeys = Object.keys(permissionsConfig.entities)
+    const unmatchedEntities = []
+
+    for (const entityKey of permissionEntityKeys) {
+      if (!knownEntitySlugs.has(entityKey)) {
+        // Try to find similar slugs for helpful error message
+        const similarSlugs = [...knownEntitySlugs].filter(slug => {
+          // Check for common variations: kebab vs camelCase, plural vs singular
+          const normalized = slug.toLowerCase().replace(/-/g, '')
+          const keyNormalized = entityKey.toLowerCase().replace(/-/g, '')
+          return normalized === keyNormalized ||
+                 slug.includes(entityKey) ||
+                 entityKey.includes(slug)
+        })
+
+        unmatchedEntities.push({
+          key: entityKey,
+          suggestions: similarSlugs
+        })
+      }
+    }
+
+    if (unmatchedEntities.length > 0) {
+      const errorLines = [
+        '',
+        '╔══════════════════════════════════════════════════════════════════════════════╗',
+        '║  PERMISSIONS CONFIG ERROR: Entity slug mismatch detected                     ║',
+        '╚══════════════════════════════════════════════════════════════════════════════╝',
+        '',
+        'The following keys in permissions.config.ts → entities do not match any',
+        'discovered entity slug. This will cause permission checks to fail at runtime.',
+        ''
+      ]
+
+      for (const { key, suggestions } of unmatchedEntities) {
+        errorLines.push(`  ❌ "${key}" - No entity found with this slug`)
+        if (suggestions.length > 0) {
+          errorLines.push(`     Did you mean: ${suggestions.map(s => `"${s}"`).join(', ')}?`)
+        }
+      }
+
+      errorLines.push('')
+      errorLines.push('Available entity slugs:')
+      errorLines.push(`  ${[...knownEntitySlugs].sort().join(', ')}`)
+      errorLines.push('')
+      errorLines.push('Fix: Ensure the key in permissions.config.ts → entities matches')
+      errorLines.push('     the "slug" field in the corresponding entity.config.ts')
+      errorLines.push('')
+
+      throw new Error(errorLines.join('\n'))
+    }
+
+    log('  ✅ All permission entity keys validated against discovered entities', 'info')
+
     for (const [entitySlug, actions] of Object.entries(permissionsConfig.entities)) {
       if (!Array.isArray(actions)) continue
 
@@ -75,110 +138,14 @@ export async function generatePermissionsRegistry(permissionsConfig, entities, c
     }
   }
 
-  // FALLBACK: For entities NOT defined in permissions.config.ts, try entity.config.ts
-  // This provides backwards compatibility during migration
-  const extractPermissionsFromFile = async (filePath, entityName, displayName) => {
-    try {
-      const content = await readFile(filePath, 'utf8')
-      const permStartIdx = content.indexOf('permissions:')
-      if (permStartIdx === -1) {
-        verbose(`  No permissions section in ${entityName}`)
-        return []
-      }
-
-      const actionsStartIdx = content.indexOf('actions:', permStartIdx)
-      if (actionsStartIdx === -1) {
-        verbose(`  No actions array in ${entityName}`)
-        return []
-      }
-
-      const arrayStartIdx = content.indexOf('[', actionsStartIdx)
-      if (arrayStartIdx === -1) return []
+  // NOTE: Entity permissions are now ONLY read from permissions.config.ts (centralized)
+  // The legacy fallback to entity.config.ts has been removed.
+  // All entity permissions must be defined in permissions.config.ts -> entities
 
-      let bracketCount = 1
-      let i = arrayStartIdx + 1
-      while (i < content.length && bracketCount > 0) {
-        if (content[i] === '[') bracketCount++
-        if (content[i] === ']') bracketCount--
-        i++
-      }
-
-      const actionsContent = content.slice(arrayStartIdx + 1, i - 1)
-      const actionRegex = /\{[^{}]*action:\s*['"](\w+)['"][^{}]*\}/g
-      const permissions = []
-      let match
-
-      while ((match = actionRegex.exec(actionsContent)) !== null) {
-        const actionBlock = match[0]
-        const action = match[1]
-
-        const labelMatch = actionBlock.match(/label:\s*['"]([^'"]+)['"]/)
-        const label = labelMatch ? labelMatch[1] : `${action.charAt(0).toUpperCase() + action.slice(1)} ${displayName}`
-
-        const rolesMatch = actionBlock.match(/roles:\s*\[([^\]]+)\]/)
-        const roles = rolesMatch
-          ? rolesMatch[1].split(',').map(r => r.trim().replace(/['"]/g, ''))
-          : ['owner', 'admin']
-
-        const dangerousMatch = actionBlock.match(/dangerous:\s*(true|false)/)
-        const dangerous = dangerousMatch ? dangerousMatch[1] === 'true' : false
-
-        permissions.push({
-          id: `${entityName}.${action}`,
-          label,
-          description: `${action} permission for ${displayName}`,
-          category: displayName,
-          roles,
-          dangerous,
-          source: 'theme'
-        })
-      }
-      return permissions
-    } catch (err) {
-      verbose(`  Error reading ${entityName}: ${err.message}`)
-      return []
-    }
-  }
-
-  // Only process entities NOT already handled by permissions.config.ts
+  // Log entities without permissions in permissions.config.ts
   for (const entity of entities) {
-    if (processedEntities.has(entity.name)) {
-      verbose(`  Skipping ${entity.name} - already processed from permissions.config.ts`)
-      continue
-    }
-
-    try {
-      const realConfigPath = resolveAliasPath(entity.configPath)
-      const configModule = await import(realConfigPath)
-      const config = configModule[entity.exportName]
-
-      if (config?.permissions?.actions && Array.isArray(config.permissions.actions)) {
-        for (const perm of config.permissions.actions) {
-          entityPermissions.push({
-            id: `${entity.name}.${perm.action}`,
-            label: perm.label || `${perm.action.charAt(0).toUpperCase() + perm.action.slice(1)} ${entity.displayName || entity.name}`,
-            description: perm.description || `${perm.action} permission for ${entity.displayName || entity.name}`,
-            category: entity.displayName || entity.name,
-            roles: perm.roles || ['owner', 'admin'],
-            dangerous: perm.dangerous || false,
-            source: entity.source || 'theme'
-          })
-        }
-        log(`  ⚠️ Extracted ${config.permissions.actions.length} permissions from ${entity.name} (LEGACY: entity.config.ts)`, 'warning')
-      }
-    } catch (err) {
-      const realConfigPath = resolveAliasPath(entity.configPath)
-      const extracted = await extractPermissionsFromFile(
-        realConfigPath,
-        entity.name,
-        entity.displayName || entity.name
-      )
-      if (extracted.length > 0) {
-        entityPermissions.push(...extracted)
-        log(`  ⚠️ Extracted ${extracted.length} permissions from ${entity.name} (LEGACY: regex fallback)`, 'warning')
-      } else {
-        verbose(`No permissions for ${entity.name} (not in permissions.config.ts and no entity.config.ts permissions)`)
-      }
+    if (!processedEntities.has(entity.name)) {
+      verbose(`  ℹ️ No permissions defined for ${entity.name} in permissions.config.ts`)
     }
   }