create-fluxstack 1.10.1 → 1.12.1

package/LLMD/resources/routes-eden.md

@@ -0,0 +1,254 @@
+# Routes with Eden Treaty
+
+**Version:** 1.11.0 | **Updated:** 2025-02-08
+
+## Quick Facts
+
+- Routes use Elysia with `t.Object()` validation schemas
+- **Response schemas are REQUIRED** for Eden Treaty type inference
+- Frontend gets automatic type inference via Eden Treaty
+- Route grouping uses `prefix` option
+- Validation happens automatically via schemas
+
+## Route Definition Pattern
+
+```typescript
+import { Elysia, t } from 'elysia'
+
+export const usersRoutes = new Elysia({ prefix: '/users', tags: ['Users'] })
+  .get('/', async () => {
+    // Handler logic
+    return { success: true, users: [], count: 0 }
+  }, {
+    detail: {
+      summary: 'Get All Users',
+      description: 'Retrieves a list of all registered users',
+      tags: ['Users', 'CRUD']
+    },
+    response: t.Object({
+      success: t.Boolean(),
+      users: t.Array(UserSchema),
+      count: t.Number()
+    })
+  })
+```
+
+## Schema Definition
+
+Define schemas at the top of route files:
+
+```typescript
+const UserSchema = t.Object({
+  id: t.Number(),
+  name: t.String(),
+  email: t.String()
+}, {
+  description: 'User object'
+})
+
+const CreateUserRequestSchema = t.Object({
+  name: t.String({ minLength: 2, description: 'User name (minimum 2 characters)' }),
+  email: t.String({ format: 'email', description: 'Valid email address' })
+}, {
+  description: 'Request body for creating a new user'
+})
+```
+
+## Response Schema (REQUIRED!)
+
+**Every route MUST define a response schema** for Eden Treaty type inference:
+
+```typescript
+.get('/users', async () => {
+  return { success: true, users: [] }
+}, {
+  response: t.Object({
+    success: t.Boolean(),
+    users: t.Array(UserSchema)
+  })
+})
+```
+
+Without response schema, frontend loses type inference.
+
+## Multiple Status Code Responses
+
+```typescript
+.post('/', async ({ body, set }) => {
+  // Validation error
+  if (!body.name) {
+    set.status = 400
+    return { success: false, error: 'Name required' }
+  }
+  
+  // Success
+  set.status = 201
+  return { success: true, user: newUser }
+}, {
+  body: CreateUserRequestSchema,
+  response: {
+    201: t.Object({
+      success: t.Literal(true),
+      user: UserSchema
+    }),
+    400: t.Object({
+      success: t.Literal(false),
+      error: t.String()
+    })
+  }
+})
+```
+
+## Route Parameters
+
+```typescript
+.get('/:id', async ({ params }) => {
+  const id = Number(params.id)
+  return { success: true, user: foundUser }
+}, {
+  params: t.Object({
+    id: t.String({ description: 'User ID' })
+  }),
+  response: {
+    200: GetUserResponseSchema,
+    404: ErrorResponseSchema
+  }
+})
+```
+
+## Request Body Validation
+
+```typescript
+.post('/', async ({ body }) => {
+  // body is automatically validated against schema
+  const user = await createUser(body)
+  return { success: true, user }
+}, {
+  body: t.Object({
+    name: t.String({ minLength: 2 }),
+    email: t.String({ format: 'email' })
+  }),
+  response: CreateUserResponseSchema
+})
+```
+
+## Route Grouping
+
+```typescript
+// Main API routes with prefix
+export const apiRoutes = new Elysia({ prefix: "/api" })
+  .get("/health", () => ({ status: "ok" }), {
+    response: t.Object({ status: t.String() })
+  })
+  // Register sub-routes
+  .use(usersRoutes)
+  .use(postsRoutes)
+```
+
+## Frontend Usage (Eden Treaty)
+
+Once routes are defined with response schemas, frontend gets automatic type inference:
+
+```typescript
+import { api } from '@/lib/eden-api'
+
+// GET request - types inferred from response schema
+const { data, error } = await api.users.get()
+// data: { success: boolean, users: User[], count: number } | undefined
+// error: Error | undefined
+
+// POST request - body type inferred from body schema
+const { data, error } = await api.users.post({
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+// TypeScript validates body matches CreateUserRequestSchema
+
+// Path parameters
+const { data } = await api.users({ id: '123' }).get()
+
+// Query parameters
+const { data } = await api.users.get({ 
+  query: { page: 1, limit: 10 } 
+})
+```
+
+## Type Flow Diagram
+
+```
+Backend Route Definition
+  ↓
+t.Object() Schema (response)
+  ↓
+Eden Treaty Type Inference
+  ↓
+Frontend api.users.get()
+  ↓
+Typed { data, error }
+```
+
+## Common Validation Types
+
+```typescript
+// String validations
+t.String({ minLength: 2, maxLength: 100 })
+t.String({ format: 'email' })
+t.String({ pattern: '^[a-z]+$' })
+
+// Number validations
+t.Number({ minimum: 0, maximum: 100 })
+t.Integer()
+
+// Arrays
+t.Array(t.String())
+t.Array(UserSchema, { minItems: 1 })
+
+// Optional fields
+t.Optional(t.String())
+
+// Unions (multiple types)
+t.Union([
+  t.Object({ success: t.Literal(true), data: t.Any() }),
+  t.Object({ success: t.Literal(false), error: t.String() })
+])
+
+// Enums
+t.Union([t.Literal('active'), t.Literal('inactive')])
+```
+
+## OpenAPI Documentation
+
+The `detail` object generates OpenAPI/Swagger documentation:
+
+```typescript
+.get('/users', handler, {
+  detail: {
+    summary: 'Get All Users',
+    description: 'Retrieves a list of all registered users',
+    tags: ['Users', 'CRUD']
+  },
+  response: ResponseSchema
+})
+```
+
+Access Swagger UI at `/swagger` when server is running.
+
+## Critical Rules
+
+**ALWAYS:**
+- Define response schema for every route
+- Use `t.Object()` for validation
+- Set `set.status` for non-200 responses
+- Define schemas at file top for reusability
+
+**NEVER:**
+- Omit response schema (breaks type inference)
+- Use plain objects without `t.Object()`
+- Forget to validate user input
+- Mix route logic with business logic (use controllers)
+
+## Related
+
+- [Controllers & Services](./controllers.md)
+- [Type Safety Patterns](../patterns/type-safety.md)
+- [Anti-Patterns](../patterns/anti-patterns.md)

package/README.md

@@ -61,20 +61,35 @@
 
 ---
 
-## 🚀 Quick Start
-
-```bash
-# Create a new FluxStack app
-bunx create-fluxstack my-awesome-app
-cd my-awesome-app
-bun run dev
-```
+## 🚀 Quick Start
+
+```bash
+# Create a new FluxStack app
+bunx create-fluxstack my-awesome-app
+cd my-awesome-app
+bun run dev
+```
 
 **That's it!** Your full-stack app is running at:
 
 - 🌐 **Frontend & Backend**: http://localhost:3000
 - 📚 **API Documentation**: http://localhost:3000/swagger
-- ⚡ **Hot Reload**: Automatic on file changes
+- ⚡ **Hot Reload**: Automatic on file changes
+
+### 🔀 Frontend Routes (React Router v7)
+
+Default routes in the demo app:
+
+- `/` Home
+- `/counter` Live Counter
+- `/form` Live Form
+- `/upload` Live Upload
+- `/api-test` Eden Treaty API Test
+
+### 🧭 Router Package
+
+This project now uses **React Router v7** via the `react-router` package (recommended by the v7 docs).
+If you are upgrading from an older setup that used `react-router-dom`, update imports to `react-router`.
 
 ### Alternative Installation
 
@@ -111,7 +126,7 @@ bun run dev
 - ✅ **Coordinated Hot Reload** - Backend and frontend reload independently
 - ✅ **Auto-Generated Swagger** - API documentation updates automatically
 - ✅ **Docker Templates** - Production-ready multi-stage builds included
-- ✅ **AI-Focused Docs** - Special documentation for AI assistants (`ai-context/`)
+- ✅ **AI-Focused Docs** - LLM-optimized documentation (`LLMD/`)
 - ✅ **Declarative Config** - Laravel-inspired configuration system
 - ✅ **WebSocket Support** - Real-time features built-in
 - ✅ **Testing Setup** - Vitest + React Testing Library ready
@@ -200,10 +215,13 @@ FluxStack/
 ├── 🔌 plugins/                 # External Plugins
 │   └── crypto-auth/           # Example: Crypto authentication
 │
-├── 🤖 ai-context/              # AI Assistant Documentation
-│   ├── 00-QUICK-START.md      # Quick start for LLMs
-│   ├── development/           # Development patterns
-│   └── examples/              # Code examples
+├── 🤖 LLMD/                    # LLM-Optimized Documentation
+│   ├── INDEX.md               # Navigation hub
+│   ├── core/                  # Framework internals
+│   ├── config/                # Configuration system
+│   ├── resources/             # Creating routes, controllers
+│   ├── patterns/              # Best practices
+│   └── reference/             # CLI, hooks, troubleshooting
 │
 └── 📦 Package Files
     ├── package.json           # Dependencies
@@ -445,10 +463,12 @@ if (featuresConfig.enableAnalytics) {
 <td width="33%">
 
 ### 📖 **Documentation**
-- [AI Context Docs](./ai-context/)
-- [Quick Start Guide](./ai-context/00-QUICK-START.md)
-- [Development Patterns](./ai-context/development/patterns.md)
+- [LLM Documentation](./LLMD/) ⭐ **NEW**
+- [LLMD Index](./LLMD/INDEX.md) - Navigation hub
+- [Development Patterns](./LLMD/patterns/project-structure.md)
+- [CLI Reference](./LLMD/reference/cli-commands.md)
 - [CLAUDE.md](./CLAUDE.md)
+- [AI Context (deprecated)](./ai-context/)
 
 </td>
 <td width="33%">

package/app/client/index.html

@@ -7,7 +7,6 @@
     <title>Vite + React + TS</title>
   </head>
   <body>
-    <script type="module" src="/@vite/client"></script>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>
   </body>

package/app/client/src/App.tsx

@@ -1,13 +1,21 @@
 import { useState, useEffect } from 'react'
+import { Routes, Route } from 'react-router'
 import { api } from './lib/eden-api'
-import { FaFire, FaBook, FaGithub, FaClock, FaImage } from 'react-icons/fa'
 import { LiveComponentsProvider } from '@/core/client'
-import { FileUploadExample } from './live/FileUploadExample'
-import { MinimalLiveClock } from './live/MinimalLiveClock'
+import { FormDemo } from './live/FormDemo'
+import { CounterDemo } from './live/CounterDemo'
+import { UploadDemo } from './live/UploadDemo'
+import { ChatDemo } from './live/ChatDemo'
+import { RoomChatDemo } from './live/RoomChatDemo'
+import { AppLayout } from './components/AppLayout'
+import { DemoPage } from './components/DemoPage'
+import { HomePage } from './pages/HomePage'
+import { ApiTestPage } from './pages/ApiTestPage'
 
 function AppContent() {
   const [apiStatus, setApiStatus] = useState<'checking' | 'online' | 'offline'>('checking')
-  const [showDemo, setShowDemo] = useState(false)
+  const [apiResponse, setApiResponse] = useState<string>('')
+  const [isLoading, setIsLoading] = useState(false)
 
   useEffect(() => {
     checkApiStatus()
@@ -22,159 +30,108 @@ function AppContent() {
     }
   }
 
-  // If demo mode is active, show demo content
-  if (showDemo) {
-    return (
-      <div className="min-h-screen bg-gradient-to-br from-slate-900 via-purple-900 to-slate-900">
-        <div className="container mx-auto px-4 py-8">
-          {/* Header with back button */}
-          <div className="flex items-center gap-4 mb-8">
-            <button
-              onClick={() => setShowDemo(false)}
-              className="px-4 py-2 bg-white/10 backdrop-blur-sm border border-white/20 text-white rounded-lg font-medium hover:bg-white/20 transition-all"
-            >
-              ← Back
-            </button>
-            <h1 className="text-3xl font-bold bg-gradient-to-r from-blue-400 via-purple-400 to-pink-400 bg-clip-text text-transparent">
-              FluxStack Demos
-            </h1>
-          </div>
-
-          {/* Demo Content */}
-          <FileUploadExample />
-        </div>
-      </div>
-    )
+  const testHealthCheck = async () => {
+    setIsLoading(true)
+    try {
+      const { data, error } = await api.health.get()
+      setApiResponse(JSON.stringify(error ?? data, null, 2))
+    } catch (e) {
+      setApiResponse(`Error: ${e}`)
+    }
+    setIsLoading(false)
   }
 
-  return (
-    <div className="min-h-screen bg-gradient-to-br from-slate-900 via-purple-900 to-slate-900">
-      <div className="flex flex-col items-center justify-center min-h-screen px-6 text-center">
-        {/* Logo */}
-        <div className="mb-8 animate-pulse-slow">
-          <FaFire className="text-8xl text-orange-500 drop-shadow-2xl" />
-        </div>
-
-        {/* Title */}
-        <h1 className="text-6xl md:text-7xl font-bold mb-4 bg-gradient-to-r from-blue-400 via-purple-400 to-pink-400 bg-clip-text text-transparent">
-          FluxStack
-        </h1>
-
-        {/* Subtitle */}
-        <p className="text-xl md:text-2xl text-gray-300 mb-8 max-w-2xl">
-          Full-stack TypeScript framework with{' '}
-          <span className="text-purple-400 font-semibold">Bun</span>,{' '}
-          <span className="text-blue-400 font-semibold">Elysia</span>, and{' '}
-          <span className="text-cyan-400 font-semibold">React</span>
-        </p>
-
-        {/* API Status Badge */}
-        <div className="mb-12">
-          <div className={`inline-flex items-center gap-2 px-4 py-2 rounded-full text-sm font-medium transition-all ${
-            apiStatus === 'online'
-              ? 'bg-emerald-500/20 text-emerald-300 border border-emerald-500/30'
-              : apiStatus === 'offline'
-              ? 'bg-red-500/20 text-red-300 border border-red-500/30'
-              : 'bg-yellow-500/20 text-yellow-300 border border-yellow-500/30'
-          }`}>
-            <div className={`w-2 h-2 rounded-full ${
-              apiStatus === 'online' ? 'bg-emerald-400' : apiStatus === 'offline' ? 'bg-red-400' : 'bg-yellow-400'
-            }`}></div>
-            <span>{apiStatus === 'checking' ? 'Checking API...' : apiStatus === 'online' ? 'API Online' : 'API Offline'}</span>
-          </div>
-        </div>
-
-        {/* Feature Cards */}
-        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mb-12 max-w-6xl">
-          <div className="bg-white/5 backdrop-blur-sm border border-white/10 rounded-2xl p-6 hover:bg-white/10 transition-all">
-            <div className="text-3xl mb-3">⚡</div>
-            <h3 className="text-lg font-semibold text-white mb-2">Ultra Rápido</h3>
-            <p className="text-gray-400 text-sm">Bun runtime 3x mais rápido que Node.js</p>
-          </div>
-
-          <div className="bg-white/5 backdrop-blur-sm border border-white/10 rounded-2xl p-6 hover:bg-white/10 transition-all">
-            <div className="text-3xl mb-3">🔒</div>
-            <h3 className="text-lg font-semibold text-white mb-2">Type Safe</h3>
-            <p className="text-gray-400 text-sm">Eden Treaty com inferência automática</p>
-          </div>
-
-          <div className="bg-white/5 backdrop-blur-sm border border-white/10 rounded-2xl p-6 hover:bg-white/10 transition-all">
-            <div className="text-3xl mb-3">🎨</div>
-            <h3 className="text-lg font-semibold text-white mb-2">Moderno</h3>
-            <p className="text-gray-400 text-sm">React 19 + Vite + Tailwind CSS</p>
-          </div>
-
-          {/* Live Clock Card */}
-          <div className="bg-white/5 backdrop-blur-sm border border-white/10 rounded-2xl p-6 hover:bg-white/10 transition-all">
-            <div className="flex items-center gap-3 mb-3">
-              <FaClock className="text-2xl text-emerald-400" />
-              <div>
-                <h3 className="text-lg font-semibold text-white">Live Clock</h3>
-                <p className="text-gray-400 text-sm">Provido via LiveComponent</p>
-              </div>
-            </div>
-            <MinimalLiveClock />
-          </div>
-        </div>
-
-        {/* Action Buttons */}
-        <div className="flex flex-wrap gap-4 justify-center">
-          <button
-            onClick={() => setShowDemo(true)}
-            className="inline-flex items-center gap-2 px-6 py-3 bg-gradient-to-r from-emerald-500 to-teal-600 text-white rounded-xl font-medium hover:shadow-lg hover:shadow-emerald-500/50 transition-all"
-          >
-            <FaImage />
-            View Demos
-          </button>
-          <a
-            href="/swagger"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="inline-flex items-center gap-2 px-6 py-3 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-xl font-medium hover:shadow-lg hover:shadow-purple-500/50 transition-all"
-          >
-            <FaBook />
-            API Docs
-          </a>
-          <a
-            href="https://github.com/MarcosBrendonDePaula/FluxStack"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="inline-flex items-center gap-2 px-6 py-3 bg-white/10 backdrop-blur-sm border border-white/20 text-white rounded-xl font-medium hover:bg-white/20 transition-all"
-          >
-            <FaGithub />
-            GitHub
-          </a>
-          <a
-            href="/api"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="inline-flex items-center gap-2 px-6 py-3 bg-white/10 backdrop-blur-sm border border-white/20 text-white rounded-xl font-medium hover:bg-white/20 transition-all"
-          >
-            🚀 API Root
-          </a>
-        </div>
+  const testGetUsers = async () => {
+    setIsLoading(true)
+    try {
+      const { data, error } = await api.users.get()
+      setApiResponse(JSON.stringify(error ?? data, null, 2))
+    } catch (e) {
+      setApiResponse(`Error: ${e}`)
+    }
+    setIsLoading(false)
+  }
 
-        {/* Footer */}
-        <div className="mt-16 text-gray-500 text-sm">
-          <p>Desenvolvido com ❤️ usando TypeScript</p>
-        </div>
-      </div>
+  const testCreateUser = async () => {
+    setIsLoading(true)
+    try {
+      const { data, error } = await api.users.post({
+        name: `Test User ${Date.now()}`,
+        email: `test${Date.now()}@example.com`
+      })
+      setApiResponse(JSON.stringify(error ?? data, null, 2))
+    } catch (e) {
+      setApiResponse(`Error: ${e}`)
+    }
+    setIsLoading(false)
+  }
 
-      {/* Animations */}
-      <style>{`
-        @keyframes pulse-slow {
-          0%, 100% { opacity: 1; }
-          50% { opacity: 0.8; }
-        }
-        .animate-pulse-slow {
-          animation: pulse-slow 3s cubic-bezier(0.4, 0, 0.6, 1) infinite;
-        }
-      `}</style>
-    </div>
+  return (
+    <Routes>
+      <Route element={<AppLayout />}>
+        <Route path="/" element={<HomePage apiStatus={apiStatus} />} />
+        <Route
+          path="/api-test"
+          element={
+            <ApiTestPage
+              apiResponse={apiResponse}
+              isLoading={isLoading}
+              onHealth={testHealthCheck}
+              onGetUsers={testGetUsers}
+              onCreateUser={testCreateUser}
+            />
+          }
+        />
+        <Route
+          path="/form"
+          element={
+            <DemoPage
+              note={<>? Este formul?rio usa <code className="text-purple-400">Live.use()</code> - cada campo sincroniza automaticamente com o servidor!</>}
+            >
+              <FormDemo />
+            </DemoPage>
+          }
+        />
+        <Route
+          path="/counter"
+          element={
+            <DemoPage>
+              <CounterDemo />
+            </DemoPage>
+          }
+        />
+        <Route
+          path="/upload"
+          element={
+            <DemoPage>
+              <UploadDemo />
+            </DemoPage>
+          }
+        />
+        <Route
+          path="/chat"
+          element={
+            <DemoPage>
+              <ChatDemo />
+            </DemoPage>
+          }
+        />
+        <Route
+          path="/room-chat"
+          element={
+            <DemoPage
+              note={<>🚀 Chat com múltiplas salas usando o novo sistema <code className="text-purple-400">$room</code>!</>}
+            >
+              <RoomChatDemo />
+            </DemoPage>
+          }
+        />
+        <Route path="*" element={<HomePage apiStatus={apiStatus} />} />
+      </Route>
+    </Routes>
   )
 }
 
-// Main App with LiveComponentsProvider
 function App() {
   return (
     <LiveComponentsProvider