@nextsparkjs/core 0.1.0-beta.8 → 0.1.0-beta.81

package/templates/app/api/v1/users/docs.md

@@ -0,0 +1,93 @@
+# Users API
+
+Manage user profiles and account settings.
+
+## Overview
+
+The Users API allows you to view and update user profile information. Users can update their own profile, while admins can manage other users within their team.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### Get Current User
+`GET /api/v1/users/me`
+
+Returns the currently authenticated user's profile.
+
+**Example Response:**
+```json
+{
+  "id": "user_123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "image": "/uploads/avatar.png",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "teams": [
+    {
+      "id": "team_456",
+      "name": "Acme Corp",
+      "role": "admin"
+    }
+  ]
+}
+```
+
+### Update Current User
+`PATCH /api/v1/users/me`
+
+Update the current user's profile.
+
+**Request Body:**
+```json
+{
+  "name": "John Smith",
+  "image": "/uploads/new-avatar.png"
+}
+```
+
+### List Team Members
+`GET /api/v1/users`
+
+Returns all users in the current team.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `search` (string, optional): Search by name or email
+
+### Get User by ID
+`GET /api/v1/users/[id]`
+
+Returns a specific user's profile (within the same team).
+
+**Path Parameters:**
+- `id` (string, required): User ID
+
+## User Roles
+
+Team-level roles determine permissions:
+- `member` - Basic team member
+- `admin` - Can manage team settings and members
+- `owner` - Full control of the team
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - User doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Auth](/api/v1/auth)** - Authentication and session management
+- **[Teams](/api/v1/teams)** - Team membership and roles
+- **[Team Invitations](/api/v1/team-invitations)** - Invite users to teams
+- **[API Keys](/api/v1/api-keys)** - Manage programmatic access

package/templates/app/api/v1/users/presets.ts

@@ -0,0 +1,59 @@
+/**
+ * API Presets for Users
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/users',
+  summary: 'Manage user profiles and team members',
+  presets: [
+    {
+      id: 'get-me',
+      title: 'Get Current User',
+      description: 'Fetch the currently authenticated user profile',
+      method: 'GET',
+      pathParams: {
+        id: 'me'
+      },
+      tags: ['read', 'profile']
+    },
+    {
+      id: 'list-team-members',
+      title: 'List Team Members',
+      description: 'Fetch all users in the current team',
+      method: 'GET',
+      params: {
+        limit: 20,
+        offset: 0
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'update-profile',
+      title: 'Update My Profile',
+      description: 'Update current user name',
+      method: 'PATCH',
+      pathParams: {
+        id: 'me'
+      },
+      payload: {
+        name: 'Updated Name'
+      },
+      tags: ['write', 'profile']
+    },
+    {
+      id: 'search-users',
+      title: 'Search Team Members',
+      description: 'Search users by name or email',
+      method: 'GET',
+      params: {
+        search: 'john',
+        limit: 10
+      },
+      tags: ['read', 'search']
+    }
+  ]
+})

package/templates/app/dashboard/(main)/[entity]/[id]/page.tsx

@@ -1,9 +1,14 @@
 import { notFound, redirect } from 'next/navigation'
-import { getEntity, getEntityRegistry, getChildEntities } from '@nextsparkjs/core/lib/entities/queries'
+import { getEntity, getEntityRegistry, getChildEntities, setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
 import { EntityDetailWrapper } from '@nextsparkjs/core/components/entities/wrappers/EntityDetailWrapper'
 import type { Metadata } from 'next'
 import { TemplateService } from '@nextsparkjs/core/lib/services/template.service'
 import type { EntityConfig, ChildEntityDefinition } from '@nextsparkjs/core/lib/entities/types'
+// Import registry directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
+
+// Initialize registry at module load time (before any component renders)
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
 
 // Type guard to check if entity is a full EntityConfig
 function isEntityConfig(entity: EntityConfig | ChildEntityDefinition): entity is EntityConfig {
@@ -33,12 +38,11 @@ async function EntityDetailPage({ params }: PageProps) {
   }
 
   // Verificar que la entidad existe en el registro
-  const registry = getEntityRegistry()
-  if (!(entitySlug in registry)) {
+  if (!(entitySlug in getEntityRegistry())) {
     notFound()
   }
 
-  const entityConfig = getEntity(entitySlug)
+  const entityConfig = getEntity(entitySlug as string)
   if (!entityConfig || !isEntityConfig(entityConfig)) {
     notFound()
   }
@@ -61,7 +65,7 @@ async function EntityDetailPage({ params }: PageProps) {
   }
 
   // Get child entities for this parent entity
-  const childEntities = getChildEntities(entitySlug)
+  const childEntities = getChildEntities(entitySlug as string)
   const childEntityNames = childEntities.map(child => child.name)
 
   return (
@@ -77,14 +81,13 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   const resolvedParams = await params
   const entitySlug = resolvedParams.entity
 
-  const registry = getEntityRegistry()
-  if (!(entitySlug in registry)) {
+  if (!(entitySlug in getEntityRegistry())) {
     return {
       title: 'Not Found - Dashboard'
     }
   }
 
-  const entityConfig = getEntity(entitySlug)
+  const entityConfig = getEntity(entitySlug as string)
   if (!entityConfig || !isEntityConfig(entityConfig)) {
     return {
       title: 'Not Found - Dashboard'

package/templates/app/dashboard/(main)/[entity]/page.tsx

@@ -1,9 +1,14 @@
 import { notFound } from 'next/navigation'
-import { getEntity, getEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
+import { getEntity, getEntityRegistry, setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
 import { EntityListWrapper } from '@nextsparkjs/core/components/entities/wrappers/EntityListWrapper'
 import type { Metadata } from 'next'
 import { getTemplateOrDefault } from '@nextsparkjs/core/lib/template-resolver'
 import type { EntityConfig, ChildEntityDefinition } from '@nextsparkjs/core/lib/entities/types'
+// Import registry directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
+
+// Initialize registry at module load time (before any component renders)
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
 
 // Type guard to check if entity is a full EntityConfig
 function isEntityConfig(entity: EntityConfig | ChildEntityDefinition): entity is EntityConfig {

package/templates/app/dashboard/(main)/layout.tsx

@@ -1,33 +1,92 @@
+/**
+ * Main Dashboard Layout with Permission Checking
+ *
+ * This layout handles:
+ * 1. Entity registry initialization
+ * 2. Server-side permission validation for entity routes
+ * 3. Rendering the DashboardShell with entity navigation
+ *
+ * IMPORTANT: Permission checking MUST be in this layout (not in [entity]/layout.tsx)
+ * because (templates) routes with specific paths take precedence over dynamic [entity] routes.
+ */
+import { headers, cookies } from 'next/headers'
+import { redirect } from 'next/navigation'
 import { DashboardShell } from '@nextsparkjs/core/components/dashboard/layouts/DashboardShell'
-import { getRegisteredEntities } from '@nextsparkjs/core/lib/entities/queries'
 import { serializeEntityConfig, type SerializableEntityConfig } from '@nextsparkjs/core/lib/entities/serialization'
+import { setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
 import { getTemplateOrDefault } from '@nextsparkjs/core/lib/template-resolver'
-import { TemplateService } from '@nextsparkjs/core/lib/services/template.service'
 import type { EntityConfig, ChildEntityDefinition } from '@nextsparkjs/core/lib/entities/types'
+import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
+import { isValidPermission } from '@nextsparkjs/core/lib/permissions/init'
+import type { Permission } from '@nextsparkjs/core/lib/permissions/types'
+// Import registry directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
 
-// Debug: Check template override status at module load
-const LAYOUT_PATH = 'app/dashboard/(main)/layout.tsx'
-console.log('[MainLayout] Checking template override for:', LAYOUT_PATH)
-console.log('[MainLayout] hasTemplateOverride:', TemplateService.hasOverride(LAYOUT_PATH))
-console.log('[MainLayout] templateEntry:', TemplateService.getEntry(LAYOUT_PATH)?.template?.themeName)
+// Register entities globally so other parts of the app can access them via getRegisteredEntities()
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
+
+type EntityAction = 'list' | 'read' | 'create' | 'update' | 'delete'
+
+/**
+ * Parse entity and action from pathname
+ * Handles paths like: /dashboard/ai-agents, /dashboard/ai-agents/create, /dashboard/ai-agents/[id]/edit
+ */
+function parseEntityFromPathname(pathname: string): { entity: string; action: EntityAction } | null {
+  const match = pathname.match(/^\/dashboard\/([^/]+)(?:\/(.*))?$/)
+  if (!match) return null
+
+  const entity = match[1]
+  const rest = match[2] || ''
+
+  if (rest === '' || rest === '/') return { entity, action: 'list' }
+  if (rest === 'create') return { entity, action: 'create' }
+  if (rest.match(/^[^/]+\/edit$/)) return { entity, action: 'update' }
+  if (rest.match(/^[^/]+$/)) return { entity, action: 'read' }
+
+  return { entity, action: 'read' }
+}
 
 // Type guard to check if entity is a full EntityConfig
 function isEntityConfig(entity: EntityConfig | ChildEntityDefinition): entity is EntityConfig {
   return 'slug' in entity
 }
 
-// Default main dashboard layout component
-// Note: AuthGuard removed - authentication guaranteed by parent CoreDashboardLayout
-function DefaultMainDashboardLayout({
+// Default main dashboard layout component with permission checking
+async function DefaultMainDashboardLayout({
   children
 }: {
   children: React.ReactNode
 }) {
-  const allEntities = getRegisteredEntities()
-  // Filter to only include full EntityConfig (not child entities)
+  // Get entities directly from the imported registry
+  const allEntities = Object.values(ENTITY_REGISTRY).map(entry => entry.config)
   const entities = allEntities.filter(isEntityConfig)
   const serializedEntities: SerializableEntityConfig[] = entities.map(serializeEntityConfig)
 
+  // === PERMISSION CHECK ===
+  const headersList = await headers()
+  const cookieStore = await cookies()
+
+  const pathname = headersList.get('x-pathname') || ''
+  const userId = headersList.get('x-user-id')
+  const teamId = cookieStore.get('activeTeamId')?.value
+
+  if (userId && teamId && pathname) {
+    const parsed = parseEntityFromPathname(pathname)
+
+    if (parsed) {
+      const { entity, action } = parsed
+      const permission = `${entity}.${action}` as Permission
+
+      if (isValidPermission(`${entity}.list` as Permission)) {
+        const hasPermission = await checkPermission(userId, teamId, permission)
+
+        if (!hasPermission) {
+          redirect(`/dashboard/permission-denied?entity=${entity}&action=${action}`)
+        }
+      }
+    }
+  }
+
   return (
     <DashboardShell entities={serializedEntities}>
       {children}
@@ -36,4 +95,4 @@ function DefaultMainDashboardLayout({
 }
 
 // Export the resolved component (theme override or default)
-export default getTemplateOrDefault('app/dashboard/(main)/layout.tsx', DefaultMainDashboardLayout)
+export default getTemplateOrDefault('app/dashboard/(main)/layout.tsx', DefaultMainDashboardLayout)

package/templates/app/dashboard/(main)/loading.tsx

@@ -0,0 +1,5 @@
+import { SkeletonDashboardHome } from '@nextsparkjs/core/components/ui/skeleton-dashboard'
+
+export default function DashboardLoading() {
+  return <SkeletonDashboardHome />
+}

package/templates/app/dashboard/(main)/page.tsx

@@ -78,7 +78,7 @@ function DefaultDashboardPage() {
         <div className="mb-8" data-cy="dashboard-welcome">
           <h1 className="text-3xl font-bold">{t('title')}</h1>
           <p className="text-muted-foreground mt-1">
-            {t('welcome', { name: user?.firstName || user?.email || '' })}
+            {t('welcome', { name: user.firstName || user.email })}
           </p>
         </div>
 
@@ -102,8 +102,6 @@ function DefaultDashboardPage() {
           ))}
         </div>
 
-
-
         {/* Quick Actions */}
         <Card>
           <CardHeader>

package/templates/app/dashboard/(main)/patterns/[id]/edit/page.tsx

@@ -0,0 +1,114 @@
+/**
+ * Patterns Edit Page
+ *
+ * Wrapper that delegates to the BuilderEditorView for pattern editing.
+ */
+
+'use client'
+
+import { notFound, useRouter } from 'next/navigation'
+import { useParams } from 'next/navigation'
+import { useEffect, useState } from 'react'
+import { clientEntityRegistry, ensureClientInitialized, type ClientEntityConfig } from '@nextsparkjs/registries/entity-registry.client'
+import { EntityFormWrapper } from '@nextsparkjs/core/components/entities/wrappers/EntityFormWrapper'
+import { BuilderEditorView } from '@nextsparkjs/core/components/dashboard/block-editor/builder-editor-view'
+import { Alert, AlertDescription } from '@nextsparkjs/core/components/ui/alert'
+import { getEntityData } from '@nextsparkjs/core/lib/api/entities'
+
+export default function PatternEditPage() {
+  const params = useParams()
+  const router = useRouter()
+  const [entityConfig, setEntityConfig] = useState<ClientEntityConfig | null>(null)
+  const [initialData, setInitialData] = useState<Record<string, unknown> | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  const entitySlug = 'patterns'
+  const entityId = params.id as string
+
+  useEffect(() => {
+    async function loadEntityData() {
+      if (!entityId) {
+        setLoading(false)
+        return
+      }
+
+      try {
+        await ensureClientInitialized()
+        const config = clientEntityRegistry.getBySlug(entitySlug)
+
+        if (!config) {
+          setEntityConfig(null)
+          setLoading(false)
+          return
+        }
+
+        setEntityConfig(config)
+
+        // For builder-enabled entities, BuilderEditorView handles its own data fetching
+        // For regular entities, fetch data here
+        if (!config.builder?.enabled) {
+          const data = await getEntityData(entitySlug, entityId, true)
+          setInitialData(data as Record<string, unknown>)
+        }
+      } catch (error) {
+        console.error('Error loading pattern:', error)
+        setEntityConfig(null)
+        setInitialData(null)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    loadEntityData()
+  }, [entityId])
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-[400px]">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
+      </div>
+    )
+  }
+
+  if (!entityConfig || !entityConfig.features?.enabled) {
+    return (
+      <Alert>
+        <AlertDescription>
+          Patterns entity is not configured or not enabled.
+        </AlertDescription>
+      </Alert>
+    )
+  }
+
+  // Use BuilderEditorView for builder-enabled entities
+  if (entityConfig.builder?.enabled) {
+    return (
+      <BuilderEditorView
+        entitySlug={entitySlug}
+        entityConfig={entityConfig}
+        id={entityId}
+        mode="edit"
+      />
+    )
+  }
+
+  // For non-builder entities, we need the initial data
+  if (!initialData) {
+    notFound()
+  }
+
+  // Use EntityFormWrapper for regular entities
+  return (
+    <EntityFormWrapper
+      entityType={entitySlug}
+      id={entityId}
+      mode="edit"
+      onSuccess={() => {
+        router.push(`/dashboard/${entitySlug}/${entityId}`)
+      }}
+      onError={(error) => {
+        console.error('Error updating pattern:', error)
+      }}
+    />
+  )
+}

package/templates/app/dashboard/(main)/patterns/[id]/page.tsx

@@ -0,0 +1,20 @@
+/**
+ * Patterns Detail Page
+ *
+ * For builder-enabled entities like patterns, this redirects to edit mode.
+ */
+
+import { redirect } from 'next/navigation'
+
+interface PageProps {
+  params: Promise<{
+    id: string
+  }>
+}
+
+export default async function PatternDetailPage({ params }: PageProps) {
+  const resolvedParams = await params
+
+  // Patterns are builder-enabled, so redirect to edit view
+  redirect(`/dashboard/patterns/${resolvedParams.id}/edit`)
+}

package/templates/app/dashboard/(main)/patterns/[id]/reports/page.tsx

@@ -0,0 +1,171 @@
+/**
+ * Pattern Usage Reports Page
+ *
+ * Shows detailed usage reports for a specific pattern.
+ * Displays stats cards and a table of entities using the pattern.
+ */
+
+'use client'
+
+import { useParams, useRouter } from 'next/navigation'
+import { useEffect, useState } from 'react'
+import Link from 'next/link'
+import { ArrowLeft, Edit, LayoutGrid } from 'lucide-react'
+import { clientEntityRegistry, ensureClientInitialized } from '@nextsparkjs/registries/entity-registry.client'
+import { PatternUsageReport } from '@nextsparkjs/core/components/patterns/PatternUsageReport'
+import { Button } from '@nextsparkjs/core/components/ui/button'
+import { Alert, AlertDescription, AlertTitle } from '@nextsparkjs/core/components/ui/alert'
+import { Skeleton } from '@nextsparkjs/core/components/ui/skeleton'
+import { getEntityData } from '@nextsparkjs/core/lib/api/entities'
+
+interface PatternData {
+  id: string
+  name?: string
+  title?: string
+}
+
+export default function PatternReportsPage() {
+  const params = useParams()
+  const router = useRouter()
+  const patternId = params.id as string
+
+  const [pattern, setPattern] = useState<PatternData | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    async function loadPattern() {
+      if (!patternId) {
+        setError('Pattern ID is required')
+        setLoading(false)
+        return
+      }
+
+      try {
+        // Ensure entity registry is initialized
+        await ensureClientInitialized()
+        const config = clientEntityRegistry.getBySlug('patterns')
+
+        if (!config || !config.features?.enabled) {
+          setError('Patterns entity is not configured or not enabled')
+          setLoading(false)
+          return
+        }
+
+        // Load pattern data
+        const data = await getEntityData('patterns', patternId, false) as PatternData
+        setPattern(data)
+      } catch (err) {
+        console.error('Error loading pattern:', err)
+        setError(err instanceof Error ? err.message : 'Failed to load pattern')
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    loadPattern()
+  }, [patternId])
+
+  if (loading) {
+    return (
+      <div className="p-6 space-y-6" data-cy="pattern-reports-loading">
+        <div className="flex items-center gap-4">
+          <Skeleton className="h-8 w-8" />
+          <Skeleton className="h-8 w-64" />
+        </div>
+        <Skeleton className="h-4 w-96" />
+        <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+          {[...Array(4)].map((_, i) => (
+            <Skeleton key={i} className="h-24" />
+          ))}
+        </div>
+        <Skeleton className="h-64" />
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="p-6" data-cy="pattern-reports-error">
+        <Alert variant="destructive">
+          <AlertTitle>Error</AlertTitle>
+          <AlertDescription>{error}</AlertDescription>
+        </Alert>
+        <Button
+          variant="outline"
+          className="mt-4"
+          onClick={() => router.push('/dashboard/patterns')}
+        >
+          <ArrowLeft className="mr-2 h-4 w-4" />
+          Back to Patterns
+        </Button>
+      </div>
+    )
+  }
+
+  if (!pattern) {
+    return (
+      <div className="p-6" data-cy="pattern-reports-not-found">
+        <Alert>
+          <AlertTitle>Pattern Not Found</AlertTitle>
+          <AlertDescription>
+            The pattern you are looking for does not exist or has been deleted.
+          </AlertDescription>
+        </Alert>
+        <Button
+          variant="outline"
+          className="mt-4"
+          onClick={() => router.push('/dashboard/patterns')}
+        >
+          <ArrowLeft className="mr-2 h-4 w-4" />
+          Back to Patterns
+        </Button>
+      </div>
+    )
+  }
+
+  const patternName = pattern.name || pattern.title || pattern.id
+
+  return (
+    <div className="p-6 space-y-6" data-cy="pattern-reports-page">
+      {/* Header */}
+      <div className="flex flex-col gap-4 md:flex-row md:items-center md:justify-between">
+        <div className="flex items-center gap-4">
+          <Button
+            variant="ghost"
+            size="icon"
+            asChild
+            data-cy="pattern-reports-back"
+          >
+            <Link href="/dashboard/patterns">
+              <ArrowLeft className="h-4 w-4" />
+            </Link>
+          </Button>
+          <div>
+            <div className="flex items-center gap-2">
+              <LayoutGrid className="h-5 w-5 text-muted-foreground" />
+              <h1 className="text-2xl font-bold tracking-tight" data-cy="pattern-reports-title">
+                {patternName}
+              </h1>
+            </div>
+            <p className="text-sm text-muted-foreground mt-1">
+              Usage reports and analytics
+            </p>
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2">
+          <Button variant="outline" asChild data-cy="pattern-reports-edit">
+            <Link href={`/dashboard/patterns/${patternId}/edit`}>
+              <Edit className="mr-2 h-4 w-4" />
+              Edit Pattern
+            </Link>
+          </Button>
+        </div>
+      </div>
+
+      {/* Usage Report */}
+      <PatternUsageReport patternId={patternId} pageSize={20} />
+    </div>
+  )
+}