@nextsparkjs/theme-default 0.1.0-beta.1

package/about/business.md

@@ -0,0 +1,49 @@
+# Business Overview
+
+## Product Name
+
+**NextSpark - Default Theme**
+
+## Description
+
+Generic multi-tenant SaaS application demonstrating a complete foundation for building business management software. Serves as both a reference implementation and starting point for custom projects.
+
+## Value Proposition
+
+Accelerate SaaS development by providing a production-ready foundation with authentication, team management, permissions, and extensible entity system out of the box.
+
+## Target Users
+
+- **Development Teams** building custom SaaS applications
+- **Agencies** needing rapid project bootstrapping
+- **Startups** creating MVPs and prototypes
+
+## Business Model
+
+Open-source boilerplate / Template-based licensing
+
+## Key Differentiators
+
+1. **True Multi-Tenancy** - Complete team isolation with role-based permissions
+2. **Entity System** - Flexible, extensible data model with built-in CRUD
+3. **Theme Architecture** - Full customization without touching core
+4. **Registry System** - High-performance dynamic configuration
+
+## Demo Scenario
+
+The default theme demonstrates a generic business management tool where:
+- Multiple companies (teams) share the platform
+- Users can belong to multiple organizations with different roles
+- Each team has isolated data (tasks, customers, invoices)
+- Permissions vary by role (owner, admin, member, viewer)
+
+## Core Capabilities
+
+- User authentication (email/password, OAuth)
+- Team management with invitations
+- Role-based access control
+- Task and customer management
+- Billing/invoices (owner-only)
+- Public pages (landing, pricing, features)
+- Internationalization (EN/ES)
+- Plugin system (AI plugin included)

package/about/features.json

@@ -0,0 +1,302 @@
+{
+  "version": "1.0.0",
+  "lastUpdated": "2024-12-18",
+  "features": {
+    "authentication": {
+      "id": "authentication",
+      "name": "Authentication",
+      "description": "User identity and access management",
+      "status": "stable",
+      "testTags": ["@feat-auth"],
+      "components": {
+        "email": {
+          "name": "Email Authentication",
+          "description": "Registration and login with email/password",
+          "testTags": ["@feat-auth", "@crud"],
+          "routes": ["/login", "/register", "/forgot-password", "/reset-password"]
+        },
+        "oauth-google": {
+          "name": "Google OAuth",
+          "description": "Social login with Google account",
+          "testTags": ["@feat-auth"],
+          "routes": ["/login"]
+        },
+        "email-verification": {
+          "name": "Email Verification",
+          "description": "Verify user email after registration",
+          "testTags": ["@feat-auth", "@workflow"],
+          "routes": ["/verify-email"]
+        }
+      }
+    },
+    "teams": {
+      "id": "teams-management",
+      "name": "Teams & Permissions",
+      "description": "Multi-tenant team management and RBAC",
+      "status": "stable",
+      "testTags": ["@feat-teams"],
+      "components": {
+        "management": {
+          "name": "Team Management",
+          "description": "Create, edit, and manage teams",
+          "testTags": ["@feat-teams", "@crud"],
+          "routes": ["/dashboard/settings/team"]
+        },
+        "switcher": {
+          "name": "Team Switcher",
+          "description": "Switch between multiple teams",
+          "testTags": ["@feat-teams", "@workflow"],
+          "routes": ["/dashboard"]
+        },
+        "invitations": {
+          "name": "Invitations",
+          "description": "Invite users to join a team",
+          "testTags": ["@feat-teams", "@workflow"],
+          "routes": ["/dashboard/settings/team/members", "/accept-invitation"]
+        },
+        "roles": {
+          "name": "Role-Based Permissions",
+          "description": "Assign roles (owner, admin, member, viewer)",
+          "testTags": ["@feat-teams", "@feat-permissions", "@security"],
+          "routes": ["/dashboard/settings/team/members"]
+        }
+      }
+    },
+    "entities": {
+      "id": "entities-management",
+      "name": "Entities",
+      "description": "Business data management with CRUD operations",
+      "status": "stable",
+      "testTags": ["@crud"],
+      "components": {
+        "tasks": {
+          "name": "Tasks",
+          "description": "Task management with search, filter, and bulk actions",
+          "testTags": ["@feat-tasks", "@crud", "@metas", "@search"],
+          "routes": ["/dashboard/tasks"]
+        },
+        "customers": {
+          "name": "Customers",
+          "description": "Customer records with contact info and metadata",
+          "testTags": ["@feat-customers", "@crud", "@metas", "@search"],
+          "routes": ["/dashboard/customers"]
+        },
+        "invoices": {
+          "name": "Invoices",
+          "description": "Billing invoices (owner-only access)",
+          "testTags": ["@crud", "@security"],
+          "routes": ["/dashboard/invoices"]
+        }
+      }
+    },
+    "settings": {
+      "id": "settings",
+      "name": "Settings",
+      "description": "User and team configuration",
+      "status": "stable",
+      "testTags": [],
+      "components": {
+        "profile": {
+          "name": "User Profile",
+          "description": "Edit personal information and preferences",
+          "testTags": ["@feat-users", "@crud"],
+          "routes": ["/dashboard/settings/profile"]
+        },
+        "security": {
+          "name": "Security",
+          "description": "Password change, sessions management",
+          "testTags": ["@feat-users", "@security"],
+          "routes": ["/dashboard/settings/security"]
+        },
+        "api-keys": {
+          "name": "API Keys",
+          "description": "Generate and manage API keys for programmatic access",
+          "testTags": ["@feat-api-keys", "@crud", "@security"],
+          "routes": ["/dashboard/settings/api-keys"]
+        }
+      }
+    },
+    "public-pages": {
+      "id": "public-pages",
+      "name": "Public Pages",
+      "description": "Marketing and informational pages",
+      "status": "stable",
+      "testTags": [],
+      "components": {
+        "landing": {
+          "name": "Landing Page",
+          "description": "Home page with marketing content",
+          "testTags": [],
+          "routes": ["/"]
+        },
+        "pricing": {
+          "name": "Pricing",
+          "description": "Pricing plans display",
+          "testTags": [],
+          "routes": ["/pricing"]
+        },
+        "support": {
+          "name": "Support",
+          "description": "Support information",
+          "testTags": [],
+          "routes": ["/support"]
+        }
+      }
+    },
+    "content": {
+      "id": "content-management",
+      "name": "Content Management",
+      "description": "Pages, posts, and dynamic content",
+      "status": "in-development",
+      "testTags": ["@feat-pages"],
+      "components": {
+        "page-builder": {
+          "name": "Page Builder",
+          "description": "Visual page builder with drag-and-drop blocks",
+          "testTags": ["@feat-pages", "@page-builder", "@block-crud", "@workflow"],
+          "routes": ["/dashboard/pages"]
+        },
+        "posts": {
+          "name": "Blog Posts",
+          "description": "Blog/content management system",
+          "testTags": ["@crud", "@workflow"],
+          "routes": ["/dashboard/posts", "/blog"]
+        }
+      }
+    },
+    "core": {
+      "id": "core-platform",
+      "name": "Core Platform",
+      "description": "Fundamental platform capabilities",
+      "status": "stable",
+      "testTags": [],
+      "components": {
+        "i18n": {
+          "name": "Internationalization",
+          "description": "Multi-language support (EN/ES)",
+          "testTags": [],
+          "routes": []
+        },
+        "mobile-nav": {
+          "name": "Mobile Navigation",
+          "description": "Touch-optimized bottom navigation bar",
+          "testTags": [],
+          "routes": ["/dashboard"]
+        }
+      }
+    },
+    "plugins": {
+      "id": "plugins",
+      "name": "Plugins",
+      "description": "Extended functionality via plugin system",
+      "status": "stable",
+      "testTags": [],
+      "components": {
+        "ai": {
+          "name": "AI Plugin",
+          "description": "Artificial intelligence features integration",
+          "testTags": [],
+          "routes": []
+        }
+      }
+    }
+  },
+  "flows": {
+    "onboarding": {
+      "id": "user-onboarding",
+      "name": "User Onboarding",
+      "description": "Complete flow from registration to first task creation",
+      "testTags": ["@flow-onboarding", "@smoke"],
+      "steps": [
+        "Register with email or Google",
+        "Verify email (if email registration)",
+        "Create or join a team",
+        "Explore dashboard",
+        "Create first task"
+      ],
+      "features": [
+        "authentication.email",
+        "authentication.oauth-google",
+        "authentication.email-verification",
+        "teams.management",
+        "entities.tasks"
+      ]
+    },
+    "team-collaboration": {
+      "id": "team-collaboration",
+      "name": "Team Collaboration",
+      "description": "Invite members and collaborate on tasks",
+      "testTags": ["@feat-teams", "@workflow"],
+      "steps": [
+        "Access team settings",
+        "Send invitation to new member",
+        "Member accepts invitation",
+        "Assign appropriate role",
+        "Member accesses shared tasks"
+      ],
+      "features": [
+        "teams.invitations",
+        "teams.roles",
+        "entities.tasks"
+      ]
+    },
+    "multi-team": {
+      "id": "multi-team-management",
+      "name": "Multi-Team Management",
+      "description": "User managing multiple organizations",
+      "testTags": ["@flow-team-switch", "@feat-teams", "@workflow"],
+      "steps": [
+        "Create additional team",
+        "Switch between teams",
+        "Manage different data per team",
+        "Configure separate permissions"
+      ],
+      "features": [
+        "teams.management",
+        "teams.switcher",
+        "teams.roles"
+      ]
+    },
+    "customer-lifecycle": {
+      "id": "customer-lifecycle",
+      "name": "Customer Lifecycle",
+      "description": "Managing customer relationships",
+      "testTags": ["@feat-customers", "@crud", "@workflow"],
+      "steps": [
+        "Add new customer",
+        "Add customer metadata",
+        "Create tasks related to customer",
+        "Generate invoice (owner only)"
+      ],
+      "features": [
+        "entities.customers",
+        "entities.tasks",
+        "entities.invoices"
+      ]
+    },
+    "api-integration": {
+      "id": "api-integration",
+      "name": "API Integration",
+      "description": "Programmatic access via API",
+      "testTags": ["@api", "@feat-api-keys", "@crud"],
+      "steps": [
+        "Generate API key",
+        "Authenticate API requests",
+        "Perform CRUD operations",
+        "Handle API responses"
+      ],
+      "features": [
+        "settings.api-keys",
+        "entities.tasks",
+        "entities.customers"
+      ]
+    }
+  },
+  "statusDefinitions": {
+    "stable": "Production-ready, fully tested",
+    "beta": "Feature complete, in testing",
+    "in-development": "Currently being implemented",
+    "planned": "Scheduled for future development",
+    "deprecated": "Being phased out"
+  }
+}

package/about/team.md

@@ -0,0 +1,79 @@
+# Default Theme
+
+> **Note:** This file contains fictional test data for development and QA purposes only. Users, teams, and credentials listed here are sample data used for testing the application.
+
+## Objetivo
+
+Demo genérico del boilerplate mostrando el modo `multi-tenant` con múltiples empresas, usuarios con diferentes roles, y aislamiento de datos por team.
+
+## Producto
+
+**Boilerplate** - Aplicación base para gestión de tareas y clientes con sistema completo de teams y permisos.
+
+## Teams Mode
+
+```
+multi-tenant
+```
+
+- Usuarios pueden pertenecer a múltiples teams
+- Team Switcher habilitado
+- Crear teams habilitado
+- Invitaciones habilitadas
+
+## Entidades
+
+| Entidad | Descripción |
+|---------|-------------|
+| tasks | Tareas con título, descripción, estado |
+| customers | Clientes con datos de contacto y metadata |
+| invoices | Facturas del sistema de billing (solo owners) |
+
+## Permisos
+
+### tasks
+
+| Action | owner | admin | member | viewer |
+|--------|:-----:|:-----:|:------:|:------:|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ❌ | ❌ |
+
+### customers
+
+| Action | owner | admin | member | viewer |
+|--------|:-----:|:-----:|:------:|:------:|
+| create | ✅ | ✅ | ❌ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ❌ | ❌ |
+| delete | ✅ | ❌ | ❌ | ❌ |
+
+## Usuarios de Prueba
+
+| Email | Nombre | Teams |
+|-------|--------|-------|
+| carlos.mendoza@nextspark.dev | Carlos Mendoza | Everpoint (owner), Riverstone (member) |
+| james.wilson@nextspark.dev | James Wilson | Everpoint (admin) |
+| ana.garcia@nextspark.dev | Ana García | Ironvale (owner) |
+| sofia.lopez@nextspark.dev | Sofia López | Riverstone (owner), Ironvale (admin) |
+| emily.johnson@nextspark.dev | Emily Johnson | Everpoint (member), Riverstone (admin) |
+| diego.ramirez@nextspark.dev | Diego Ramírez | Everpoint (member) |
+| michael.brown@nextspark.dev | Michael Brown | Ironvale (member) |
+| sarah.davis@nextspark.dev | Sarah Davis | Ironvale (viewer) |
+
+**Password:** `Test1234`
+
+## Teams
+
+| Team | Industria | Miembros |
+|------|-----------|----------|
+| Everpoint Labs | Technology | 4 |
+| Ironvale Global | Consulting | 4 |
+| Riverstone Ventures | Investment | 3 |
+
+## Casos de Uso
+
+1. Equipos de diferentes industrias compartiendo la misma plataforma
+2. Usuarios con diferentes roles en diferentes empresas
+3. Aislamiento completo de datos entre teams

package/api/ai/chat/stream/route.ts

@@ -0,0 +1,212 @@
+/**
+ * ============================================================================
+ * STREAMING CHAT API ENDPOINT
+ * ============================================================================
+ *
+ * Provides token-by-token streaming for AI chat using Server-Sent Events (SSE).
+ * Supports cancellation via AbortSignal and tracks token usage.
+ *
+ * POST /api/ai/chat/stream
+ *   Body:
+ *     - message: string (required) - User message
+ *     - sessionId: string (optional) - Conversation session ID
+ *     - agentName: string (required) - Agent to use (from langchain.config.ts)
+ *
+ * Returns: Server-Sent Events stream
+ *   Event types:
+ *     - token: { type: 'token', content: string }
+ *     - done: { type: 'done', fullContent: string, tokenUsage?: {...} }
+ *     - error: { type: 'error', error: string }
+ *     - tool_start: { type: 'tool_start', toolName: string }
+ *     - tool_end: { type: 'tool_end', toolName: string, result: unknown }
+ *
+ * ============================================================================
+ */
+
+import { NextRequest } from 'next/server'
+import { z } from 'zod'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { streamChat } from '@/plugins/langchain/lib/agent-factory'
+import { createSSEEncoder } from '@/plugins/langchain/lib/streaming'
+import { loadSystemPrompt } from '@/themes/default/lib/langchain/agents'
+import {
+    getAgentConfig,
+    getAgentModelConfig,
+    getAgentTools,
+    getAgentPromptName,
+} from '@/themes/default/lib/langchain/langchain.config'
+
+// Request validation schema
+const StreamChatRequestSchema = z.object({
+    message: z.string().min(1).max(2000),
+    sessionId: z.string().optional(),
+    agentName: z.string().min(1),
+})
+
+/**
+ * POST - Stream chat response
+ */
+export async function POST(request: NextRequest) {
+    try {
+        // 1. Authentication
+        const authResult = await authenticateRequest(request)
+        if (!authResult.success || !authResult.user) {
+            return new Response(
+                JSON.stringify({ success: false, error: 'Unauthorized' }),
+                {
+                    status: 401,
+                    headers: { 'Content-Type': 'application/json' },
+                }
+            ) as any
+        }
+
+        // 2. Team context
+        const teamId = request.headers.get('x-team-id')
+        if (!teamId) {
+            return new Response(
+                JSON.stringify({
+                    success: false,
+                    error: 'Team context required',
+                    code: 'TEAM_CONTEXT_REQUIRED',
+                }),
+                {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                }
+            ) as any
+        }
+
+        const userId = authResult.user.id
+        const context = { userId, teamId }
+
+        // 3. Validate request body
+        const body = await request.json()
+        const validation = StreamChatRequestSchema.safeParse(body)
+
+        if (!validation.success) {
+            return new Response(
+                JSON.stringify({
+                    success: false,
+                    error: 'Invalid request',
+                    details: validation.error.issues,
+                }),
+                {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                }
+            ) as any
+        }
+
+        const { message, sessionId, agentName } = validation.data
+
+        // 4. Get agent configuration
+        const agentConfig = getAgentConfig(agentName)
+        if (!agentConfig) {
+            return new Response(
+                JSON.stringify({
+                    success: false,
+                    error: `Agent '${agentName}' not found`,
+                    code: 'AGENT_NOT_FOUND',
+                }),
+                {
+                    status: 404,
+                    headers: { 'Content-Type': 'application/json' },
+                }
+            ) as any
+        }
+
+        // 5. Load system prompt
+        const promptName = getAgentPromptName(agentName)
+        if (!promptName) {
+            return new Response(
+                JSON.stringify({
+                    success: false,
+                    error: `No system prompt configured for agent '${agentName}'`,
+                }),
+                {
+                    status: 500,
+                    headers: { 'Content-Type': 'application/json' },
+                }
+            ) as any
+        }
+
+        const systemPrompt = loadSystemPrompt(promptName as any)
+
+        // 6. Build agent configuration for streaming
+        const streamConfig = {
+            name: agentName,
+            systemPrompt,
+            tools: getAgentTools(agentName, context),
+            modelConfig: getAgentModelConfig(agentName),
+            guardrails: agentConfig.guardrails,
+        }
+
+        // 7. Create SSE stream
+        const encoder = createSSEEncoder()
+
+        const stream = new ReadableStream({
+            async start(controller) {
+                try {
+                    // Create streaming generator
+                    const generator = streamChat(message, context, streamConfig, {
+                        sessionId,
+                        agentName,
+                        signal: request.signal,
+                    })
+
+                    // Stream chunks
+                    for await (const chunk of generator) {
+                        controller.enqueue(encoder.encode(chunk))
+
+                        // Stop streaming on done or error
+                        if (chunk.type === 'done' || chunk.type === 'error') {
+                            break
+                        }
+                    }
+
+                    // Send final marker
+                    controller.enqueue(encoder.encodeDone())
+                    controller.close()
+                } catch (error) {
+                    // Stream error to client
+                    controller.enqueue(
+                        encoder.encode({
+                            type: 'error',
+                            error: error instanceof Error ? error.message : 'Streaming error',
+                        })
+                    )
+                    controller.close()
+                }
+            },
+
+            // Handle client cancellation
+            cancel() {
+                console.log('[Streaming Chat] Stream cancelled by client')
+            },
+        })
+
+        // 8. Return SSE response
+        // Note: Returning raw Response (not NextResponse) for SSE streaming compatibility
+        return new Response(stream, {
+            headers: {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache, no-transform',
+                'Connection': 'keep-alive',
+                'X-Accel-Buffering': 'no', // Disable nginx buffering
+            },
+        }) as any // Type assertion needed - Response is compatible with NextResponse
+    } catch (error) {
+        console.error('[Streaming Chat] Error:', error)
+        return new Response(
+            JSON.stringify({
+                success: false,
+                error: 'Failed to start streaming',
+                details: error instanceof Error ? error.message : 'Unknown error',
+            }),
+            {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            }
+        ) as any
+    }
+}