nucleus-core-ts 0.8.0

package/public/components/docs/content/gettingStarted.ts

@@ -0,0 +1,627 @@
+import type { DocItem } from "../docsData";
+
+export const gettingStartedItems: DocItem[] = [
+	{
+		id: "what-is-nucleus",
+		title: "What is Nucleus",
+		subItems: [
+			{
+				id: "the-problem",
+				title: "The Problem",
+				content: `
+## The Problem
+
+Building enterprise backend applications from scratch is **time-consuming** and **error-prone**. Every new project requires developers to solve the same fundamental challenges over and over again.
+
+### Common Pain Points
+
+**1. Repetitive CRUD Operations**
+Every database table needs create, read, update, and delete endpoints. For a typical application with 20+ tables, this means writing hundreds of nearly identical route handlers.
+
+**2. Authentication Complexity**
+Implementing secure authentication involves:
+- Password hashing and verification
+- JWT token generation and validation
+- Session management
+- Token refresh mechanisms
+- Password reset flows
+- Email verification
+
+**3. Security Vulnerabilities**
+Custom implementations often have security gaps:
+- SQL injection vulnerabilities
+- Improper token storage
+- Missing rate limiting
+- Inadequate input validation
+
+**4. Inconsistent Codebases**
+When each developer implements things differently, you end up with:
+- Different error handling patterns
+- Inconsistent API response formats
+- Varied authorization approaches
+- Mixed naming conventions
+
+### The Real Cost
+
+| Task | Estimated Time |
+|------|----------------|
+| Basic CRUD for 20 tables | 40-60 hours |
+| Authentication system | 20-30 hours |
+| Session management | 10-15 hours |
+| Audit logging | 8-12 hours |
+| Email integration | 5-8 hours |
+| **Total** | **83-125 hours** |
+
+That's **2-3 weeks** of development time just for infrastructure, before writing any business logic.
+        `,
+			},
+			{
+				id: "the-solution",
+				title: "The Solution",
+				content: `
+## The Solution
+
+Nucleus Core eliminates infrastructure overhead with a **configuration-driven approach**. Define what you need, and Nucleus generates it.
+
+### How It Works
+
+\`\`\`mermaid
+flowchart LR
+    A[Define Config] --> B[Nucleus Plugin]
+    B --> C[Auto-Generated Routes]
+    B --> D[Auth System]
+    B --> E[Session Management]
+    B --> F[Audit Logging]
+    B --> G[Swagger Docs]
+    
+    style B fill:#3b82f6,color:#fff
+\`\`\`
+
+### Configuration Example
+
+\`\`\`typescript
+import { nucleusPlugin } from 'nucleus-core'
+
+const config = {
+  database: {
+    url: process.env.DATABASE_URL,
+    pushSchema: true,
+  },
+  authentication: {
+    enabled: true,
+    accessToken: { secret: process.env.JWT_SECRET, expiresIn: '15m' },
+    refreshToken: { secret: process.env.REFRESH_SECRET, expiresIn: '7d' },
+    sessionToken: { secret: process.env.SESSION_SECRET, expiresIn: '30d' },
+    login: { enabled: true, isPublic: true },
+    register: { enabled: true, isPublic: true },
+    logout: { enabled: true },
+    sessions: { enabled: true, maxActiveSessions: 5 },
+  },
+  audit: { enabled: true },
+}
+
+const app = new Elysia()
+  .use(nucleusPlugin(config))
+  .listen(3000)
+\`\`\`
+
+### What You Get
+
+| Feature | Manual Implementation | With Nucleus |
+|---------|----------------------|--------------|
+| CRUD Routes | 40-60 hours | **0 hours** (auto-generated) |
+| Authentication | 20-30 hours | **5 minutes** (config) |
+| Sessions | 10-15 hours | **2 minutes** (config) |
+| Audit Logs | 8-12 hours | **1 minute** (config) |
+| Swagger Docs | 4-6 hours | **0 hours** (auto-generated) |
+
+### Key Benefits
+
+- **Type-Safe**: Full TypeScript support with inferred types
+- **Secure by Default**: Industry-standard security practices built-in
+- **Consistent**: Uniform API patterns across all endpoints
+- **Documented**: Auto-generated OpenAPI/Swagger documentation
+- **Extensible**: Add custom routes alongside generated ones
+        `,
+			},
+			{
+				id: "the-end-game",
+				title: "The End Game",
+				content: `
+## The End Game
+
+Our vision is to make Nucleus the **standard foundation** for enterprise backend development.
+
+### Philosophy
+
+\`\`\`mermaid
+mindmap
+  root((Nucleus Philosophy))
+    Convention over Configuration
+      Sensible defaults
+      Override when needed
+    Security First
+      No shortcuts on security
+      Regular updates
+    Developer Experience
+      Minimal boilerplate
+      Clear error messages
+    Production Ready
+      Battle-tested patterns
+      Scalable architecture
+\`\`\`
+
+### Roadmap
+
+**Current (v3.x)**
+- ✅ Generic CRUD routing
+- ✅ JWT authentication
+- ✅ Session management with Redis
+- ✅ Device fingerprinting
+- ✅ Audit logging
+- ✅ Email integration (Gmail)
+- ✅ Swagger auto-generation
+
+**Planned (v4.x)**
+- 🔲 Multi-tenant support
+- 🔲 GraphQL layer
+- 🔲 Real-time subscriptions
+- 🔲 File upload management
+- 🔲 Background job queue
+- 🔲 Rate limiting per user/role
+
+**Future**
+- 🔲 Admin dashboard UI
+- 🔲 Analytics integration
+- 🔲 A/B testing framework
+- 🔲 Feature flags
+        `,
+			},
+		],
+	},
+	{
+		id: "quickstart",
+		title: "Quickstart",
+		subItems: [
+			{
+				id: "installation",
+				title: "Installation",
+				content: `
+## Installation
+
+### Prerequisites
+
+- **Bun** v1.0+ (recommended) or Node.js v18+
+- **PostgreSQL** 14+ database
+- **Redis** 6+ for session storage
+
+### Install Package
+
+\`\`\`bash
+bun add nucleus-core elysia
+\`\`\`
+
+Or with npm:
+
+\`\`\`bash
+npm install nucleus-core elysia
+\`\`\`
+
+### Peer Dependencies
+
+Nucleus requires these peer dependencies:
+
+\`\`\`bash
+bun add drizzle-orm pg ioredis
+\`\`\`
+
+### Project Structure
+
+\`\`\`
+my-api/
+├── src/
+│   ├── index.ts          # Elysia app entry
+│   ├── config.ts         # Nucleus configuration
+│   └── drizzle/
+│       ├── schema.ts     # Database schema
+│       └── index.ts      # Drizzle client
+├── .env                  # Environment variables
+├── package.json
+└── tsconfig.json
+\`\`\`
+        `,
+			},
+			{
+				id: "config-file",
+				title: "Config File",
+				content: `
+## Configuration File
+
+The configuration file is the heart of Nucleus. It defines all features and behaviors.
+
+### Basic Configuration
+
+\`\`\`typescript
+// src/config.ts
+import type { NucleusConfigOptions } from 'nucleus-core'
+import * as schema from './drizzle/schema'
+
+export const config: NucleusConfigOptions = {
+  // Database connection
+  database: {
+    url: process.env.DATABASE_URL!,
+    pushSchema: true,  // Auto-sync schema on startup
+  },
+  
+  // Drizzle schema reference
+  schema,
+  
+  // Authentication settings
+  authentication: {
+    enabled: true,
+    
+    // Access token - short-lived, for API requests
+    accessToken: {
+      secret: process.env.ACCESS_TOKEN_SECRET!,
+      expiresIn: '15m',
+      algorithm: 'HS256',
+    },
+    
+    // Refresh token - long-lived, for getting new access tokens
+    refreshToken: {
+      secret: process.env.REFRESH_TOKEN_SECRET!,
+      expiresIn: '7d',
+    },
+    
+    // Session token - identifies the session
+    sessionToken: {
+      secret: process.env.SESSION_TOKEN_SECRET!,
+      expiresIn: '30d',
+    },
+    
+    // Enable routes
+    login: { enabled: true, isPublic: true },
+    register: { enabled: true, isPublic: true },
+    logout: { enabled: true },
+    refresh: { enabled: true, isPublic: true },
+  },
+  
+  // Redis for sessions
+  redis: {
+    url: process.env.REDIS_URL || 'redis://localhost:6379',
+  },
+  
+  // Audit logging
+  audit: {
+    enabled: true,
+  },
+}
+\`\`\`
+
+### Environment Variables
+
+\`\`\`bash
+# .env
+DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
+REDIS_URL=redis://localhost:6379
+
+# Use strong, unique secrets (256-bit minimum)
+ACCESS_TOKEN_SECRET=your-access-token-secret-min-32-chars
+REFRESH_TOKEN_SECRET=your-refresh-token-secret-min-32-chars
+SESSION_TOKEN_SECRET=your-session-token-secret-min-32-chars
+\`\`\`
+        `,
+			},
+			{
+				id: "elysia-setup",
+				title: "Elysia Setup",
+				content: `
+## Elysia Integration
+
+### Basic Setup
+
+\`\`\`typescript
+// src/index.ts
+import { Elysia } from 'elysia'
+import { nucleusPlugin } from 'nucleus-core'
+import { config } from './config'
+
+const app = new Elysia()
+  // Add Nucleus plugin
+  .use(nucleusPlugin(config))
+  
+  // Add your custom routes
+  .get('/health', () => ({ status: 'ok' }))
+  
+  .listen(3000)
+
+console.log(\`
+🚀 Server running at http://localhost:3000
+📚 Swagger docs at http://localhost:3000/docs
+\`)
+\`\`\`
+
+### What Gets Created
+
+After starting the server, you'll have:
+
+| Endpoint | Description |
+|----------|-------------|
+| \`POST /auth/login\` | User authentication |
+| \`POST /auth/register\` | User registration |
+| \`POST /auth/logout\` | Session termination |
+| \`POST /auth/refresh\` | Token refresh |
+| \`GET /auth/me\` | Current user info |
+| \`GET /:entity\` | List entities (per table) |
+| \`GET /:entity/:id\` | Get single entity |
+| \`POST /:entity\` | Create entity |
+| \`PUT /:entity/:id\` | Update entity |
+| \`DELETE /:entity/:id\` | Delete entity |
+| \`GET /docs\` | Swagger documentation |
+
+### Running the Server
+
+\`\`\`bash
+bun run src/index.ts
+\`\`\`
+
+Or with watch mode:
+
+\`\`\`bash
+bun --watch run src/index.ts
+\`\`\`
+        `,
+			},
+		],
+	},
+	{
+		id: "features",
+		title: "Features",
+		subItems: [
+			{
+				id: "generic-routing",
+				title: "Generic Routing",
+				content: `
+## Generic Entity Routing
+
+Nucleus automatically creates CRUD routes for every table in your Drizzle schema.
+
+### Generated Routes
+
+| Method | Route | Description | Auth Required |
+|--------|-------|-------------|---------------|
+| \`GET\` | \`/:entity\` | List with pagination | Configurable |
+| \`GET\` | \`/:entity/:id\` | Get by ID | Configurable |
+| \`POST\` | \`/:entity\` | Create new | Configurable |
+| \`PUT\` | \`/:entity/:id\` | Update by ID | Configurable |
+| \`DELETE\` | \`/:entity/:id\` | Delete by ID | Configurable |
+| \`POST\` | \`/:entity/bulk\` | Bulk create | Configurable |
+| \`PUT\` | \`/:entity/bulk\` | Bulk update | Configurable |
+| \`DELETE\` | \`/:entity/bulk\` | Bulk delete | Configurable |
+
+### List Endpoint Features
+
+\`\`\`typescript
+// GET /users?page=1&limit=20&sort=createdAt&order=desc&search=john
+
+// Response
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "meta": {
+      "page": 1,
+      "limit": 20,
+      "totalItems": 150,
+      "totalPages": 8,
+      "hasNextPage": true,
+      "hasPrevPage": false
+    }
+  }
+}
+\`\`\`
+
+### Query Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| \`page\` | number | 1 | Page number (1-indexed) |
+| \`limit\` | number | 20 | Items per page (max 100) |
+| \`sort\` | string | 'createdAt' | Field to sort by |
+| \`order\` | 'asc' \\| 'desc' | 'desc' | Sort direction |
+| \`search\` | string | - | Search across text fields |
+
+### Authorization
+
+Control access per entity in your config:
+
+\`\`\`typescript
+entities: {
+  users: {
+    authorizedRoles: ['admin'],  // Only admins
+  },
+  posts: {
+    authorizedRoles: ['admin', 'editor'],  // Admins and editors
+  },
+  comments: {
+    authorizedRoles: [],  // Public access
+  },
+}
+\`\`\`
+        `,
+			},
+			{
+				id: "initialization",
+				title: "Initialization",
+				content: `
+## Initialization Flow
+
+Understanding the startup sequence helps with debugging and customization.
+
+### Startup Sequence
+
+\`\`\`mermaid
+sequenceDiagram
+    participant App as Your App
+    participant Nucleus
+    participant DB as PostgreSQL
+    participant Redis
+    
+    App->>Nucleus: use(nucleusPlugin(config))
+    
+    Note over Nucleus: 1. Validate Config
+    Nucleus->>Nucleus: Check required fields
+    Nucleus->>Nucleus: Apply defaults
+    
+    Note over Nucleus: 2. Database Setup
+    Nucleus->>DB: Connect
+    Nucleus->>DB: Push schema (if enabled)
+    Nucleus->>DB: Create system tables
+    
+    Note over Nucleus: 3. Redis Setup
+    Nucleus->>Redis: Connect
+    Nucleus->>Redis: Test connection
+    
+    Note over Nucleus: 4. Auth Setup
+    Nucleus->>Nucleus: Initialize JWT signing
+    Nucleus->>DB: Create/verify admin user
+    
+    Note over Nucleus: 5. Route Registration
+    Nucleus->>Nucleus: Generate entity routes
+    Nucleus->>Nucleus: Register auth routes
+    Nucleus->>Nucleus: Setup middleware
+    
+    Note over Nucleus: 6. Documentation
+    Nucleus->>Nucleus: Generate Swagger spec
+    
+    Nucleus-->>App: Plugin ready
+\`\`\`
+
+### System Tables
+
+Nucleus creates these tables automatically:
+
+| Table | Purpose |
+|-------|---------|
+| \`users\` | User accounts |
+| \`userSessions\` | Active sessions |
+| \`auditLogs\` | Operation history |
+| \`passwordResetTokens\` | Reset tokens |
+| \`magicLinkTokens\` | Magic link tokens |
+
+### Lifecycle Hooks
+
+\`\`\`typescript
+const config = {
+  // ... other config
+  
+  hooks: {
+    onReady: async (app) => {
+      console.log('Nucleus is ready!')
+    },
+    onRequest: async (context) => {
+      // Called on every request
+    },
+    beforeEntityCreate: async (entity, data) => {
+      // Called before creating any entity
+    },
+    afterEntityCreate: async (entity, data, result) => {
+      // Called after creating any entity
+    },
+  }
+}
+\`\`\`
+        `,
+			},
+			{
+				id: "concepts",
+				title: "Core Concepts",
+				content: `
+## Core Concepts
+
+Understanding these concepts will help you use Nucleus effectively.
+
+### Entities
+
+An **entity** is any database table that Nucleus manages. Each entity automatically gets:
+- CRUD API endpoints
+- Request/response validation
+- Swagger documentation
+- Audit logging
+
+### Three-Token Architecture
+
+\`\`\`mermaid
+flowchart TB
+    subgraph Tokens
+        AT[Access Token<br/>15 min lifetime]
+        RT[Refresh Token<br/>7 day lifetime]
+        ST[Session Token<br/>30 day lifetime]
+    end
+    
+    subgraph Purpose
+        AT --> P1[API Authentication]
+        RT --> P2[Get New Access Token]
+        ST --> P3[Device Tracking]
+    end
+    
+    subgraph Storage
+        AT --> S1[HTTP-Only Cookie]
+        RT --> S2[HTTP-Only Cookie]
+        ST --> S3[HTTP-Only Cookie + Redis]
+    end
+\`\`\`
+
+### Session vs Token
+
+| Aspect | Session Token | Access Token |
+|--------|--------------|--------------|
+| **Lifetime** | Long (30 days) | Short (15 min) |
+| **Storage** | Redis + Database | Stateless JWT |
+| **Revocable** | Yes, immediately | No (until expiry) |
+| **Purpose** | Device tracking | API authentication |
+| **Contains** | Session ID | User ID, permissions |
+
+### Role-Based Access Control
+
+Nucleus supports role-based authorization:
+
+\`\`\`typescript
+// User roles are stored in the users table
+{
+  id: 'uuid',
+  email: 'user@example.com',
+  role: 'admin' | 'user' | 'editor' | ...
+}
+
+// Routes check roles in middleware
+entities: {
+  sensitiveData: {
+    authorizedRoles: ['admin'],
+  }
+}
+\`\`\`
+
+### Audit Trail
+
+Every mutation is logged:
+
+\`\`\`typescript
+// Audit log entry
+{
+  id: 'uuid',
+  userId: 'uuid',        // Who
+  action: 'CREATE',      // What action
+  entityType: 'users',   // Which table
+  entityId: 'uuid',      // Which record
+  changes: {...},        // What changed
+  ipAddress: '...',      // From where
+  userAgent: '...',      // Which device
+  createdAt: '...'       // When
+}
+\`\`\`
+        `,
+			},
+		],
+	},
+];

package/public/components/docs/docsData.ts

@@ -0,0 +1,36 @@
+import { authenticationItems } from "./content/authentication";
+import { gettingStartedItems } from "./content/gettingStarted";
+
+export interface DocSubItem {
+	id: string;
+	title: string;
+	content: string;
+}
+
+export interface DocItem {
+	id: string;
+	title: string;
+	subItems: DocSubItem[];
+}
+
+export interface DocSection {
+	id: string;
+	title: string;
+	icon: string;
+	items: DocItem[];
+}
+
+export const docsData: DocSection[] = [
+	{
+		id: "getting-started",
+		title: "Getting Started",
+		icon: "🚀",
+		items: gettingStartedItems,
+	},
+	{
+		id: "authentication",
+		title: "Authentication",
+		icon: "🔐",
+		items: authenticationItems,
+	},
+];

package/public/components/docs/index.ts

@@ -0,0 +1,6 @@
+export { Docs } from "./Docs";
+export { DocsContent } from "./DocsContent";
+export { DocsRightSidebar } from "./DocsRightSidebar";
+export { DocsSidebar } from "./DocsSidebar";
+export type { DocItem, DocSection, DocSubItem } from "./docsData";
+export { docsData } from "./docsData";

package/public/components/index.ts

@@ -0,0 +1,9 @@
+export { Capabilities } from "./Capabilities";
+export { CTA } from "./CTA";
+export { Docs } from "./docs";
+export { Features } from "./Features";
+export { Footer } from "./Footer";
+export { Hero } from "./Hero";
+export { Managers } from "./Managers";
+export { Nav } from "./Nav";
+export { Stack } from "./Stack";