create-fluxstack 1.10.1 → 1.12.0

package/LLMD/patterns/anti-patterns.md

@@ -0,0 +1,297 @@
+# Anti-Patterns
+
+**Version:** 1.11.0 | **Updated:** 2025-02-08
+
+## Quick Facts
+
+- FluxStack has strict rules to maintain type safety and stability
+- Violations break type inference, cause runtime errors, or introduce security issues
+- Most issues stem from ignoring the core/app separation
+
+## Core Directory Violations
+
+### Never Modify `core/`
+
+```typescript
+// ❌ NEVER do this
+// Editing core/server/framework.ts
+// Editing core/plugins/manager.ts
+// Editing core/utils/config-schema.ts
+
+// ✅ Use extension points instead
+// Create plugins in plugins/
+// Override configs in config/
+// Add business logic in app/
+```
+
+**Why**: `core/` is framework code. Changes break on updates and can't be merged upstream.
+
+## Eden Treaty Anti-Patterns
+
+### Never Wrap Eden Treaty
+
+```typescript
+// ❌ WRONG - Wrapping breaks type inference
+async function apiCall<T>(fn: () => Promise<any>): Promise<T> {
+  try {
+    const result = await fn()
+    return result.data as T  // Type cast = lost inference
+  } catch (error) {
+    throw error
+  }
+}
+
+const user = await apiCall<User>(() => api.users({ id: 1 }).get())
+// user type is manually cast, not inferred
+
+// ✅ CORRECT - Use Eden Treaty directly
+const { data, error } = await api.users({ id: 1 }).get()
+// data is automatically typed as UserResponse
+```
+
+**Why**: Eden Treaty's power is automatic type inference. Wrappers destroy this.
+
+### Never Omit Response Schemas
+
+```typescript
+// ❌ WRONG - No response schema
+export const usersRoutes = new Elysia({ prefix: '/users' })
+  .get('/', () => {
+    return { users: [] }  // Response type is 'unknown' in Eden
+  })
+
+// ✅ CORRECT - Always define response schema
+export const usersRoutes = new Elysia({ prefix: '/users' })
+  .get('/', () => {
+    return { users: [] }
+  }, {
+    response: t.Object({
+      users: t.Array(t.Object({
+        id: t.Number(),
+        name: t.String()
+      }))
+    })
+  })
+```
+
+**Why**: Response schemas enable type inference AND generate Swagger docs.
+
+### Never Define Types Manually for API Responses
+
+```typescript
+// ❌ WRONG - Manual type definitions
+interface UserResponse {
+  id: number
+  name: string
+}
+const { data } = await api.users.get()
+const users = data as UserResponse[]  // Type assertion
+
+// ✅ CORRECT - Let Eden Treaty infer types
+const { data, error } = await api.users.get()
+// TypeScript automatically knows data.users is User[]
+```
+
+## Configuration Anti-Patterns
+
+### Never Use process.env Directly
+
+```typescript
+// ❌ WRONG - No validation, no type safety
+const port = process.env.PORT || 3000
+const debug = process.env.DEBUG === 'true'
+
+// ✅ CORRECT - Use config system
+import { appConfig } from '@config/app.config'
+const port = appConfig.port  // number, validated
+const debug = appConfig.debug  // boolean, validated
+```
+
+### Never Hardcode Configuration
+
+```typescript
+// ❌ WRONG - Hardcoded values
+const corsOrigins = ['http://localhost:5173', 'https://myapp.com']
+
+// ✅ CORRECT - Use environment-based config
+import { serverConfig } from '@config/server.config'
+const corsOrigins = serverConfig.cors.origins
+```
+
+### Never Mix Config Layers
+
+```typescript
+// ❌ WRONG - Accessing system config from app code
+import { systemConfig } from '@config/system.config'
+console.log(systemConfig.framework.name)  // Framework details in app
+
+// ✅ CORRECT - Use appropriate config layer
+import { appConfig } from '@config/app.config'
+console.log(appConfig.name)
+```
+
+## Import Path Anti-Patterns
+
+### Never Use Deep Relative Imports
+
+```typescript
+// ❌ WRONG - Brittle, hard to refactor
+import { api } from '../../../lib/eden-api'
+import type { User } from '../../../../shared/types'
+
+// ✅ CORRECT - Use path aliases
+import { api } from '@client/lib/eden-api'
+import type { User } from '@shared/types'
+```
+
+### Never Import Core Internals
+
+```typescript
+// ❌ WRONG - Internal implementation details
+import { internalHelper } from '@core/framework/internal/utils'
+
+// ✅ CORRECT - Use public exports only
+import { publicUtil } from '@core/utils'
+```
+
+## Plugin Security Anti-Patterns
+
+### Never Enable NPM Discovery Without Whitelist
+
+```bash
+# ❌ WRONG - All NPM plugins auto-loaded (dangerous!)
+PLUGINS_DISCOVER_NPM=true
+# No PLUGINS_ALLOWED set
+
+# ✅ CORRECT - Whitelist required packages
+PLUGINS_DISCOVER_NPM=true
+PLUGINS_ALLOWED=fluxstack-plugin-auth,@acme/fplugin-payments
+```
+
+### Never Skip Plugin Auditing
+
+```bash
+# ❌ WRONG - Installing without audit
+bun add some-random-plugin
+
+# ✅ CORRECT - Use plugin:add with audit
+bun run fluxstack plugin:add some-random-plugin
+# Automatically audits before install
+```
+
+### Never Trust Plugin Config Blindly
+
+```typescript
+// ❌ WRONG - Using unvalidated plugin config
+const pluginConfig = await loadPluginConfig(pluginName)
+database.connect(pluginConfig.connectionString)  // Potential injection
+
+// ✅ CORRECT - Validate with schema
+const schema = {
+  connectionString: config.string('DB_URL', '', true)
+}
+const validatedConfig = defineConfig(schema)
+```
+
+## Route Definition Anti-Patterns
+
+### Never Mix Business Logic in Routes
+
+```typescript
+// ❌ WRONG - Database logic in route
+export const usersRoutes = new Elysia({ prefix: '/users' })
+  .get('/', async () => {
+    const db = await connectDB()
+    const users = await db.query('SELECT * FROM users')
+    await db.close()
+    return { users }
+  })
+
+// ✅ CORRECT - Use controller/service pattern
+export const usersRoutes = new Elysia({ prefix: '/users' })
+  .get('/', async () => {
+    return await userController.list()
+  })
+```
+
+### Never Forget Error Handling
+
+```typescript
+// ❌ WRONG - Unhandled errors
+.post('/', async ({ body }) => {
+  const user = await createUser(body)  // May throw
+  return { user }
+})
+
+// ✅ CORRECT - Handle errors properly
+.post('/', async ({ body, error }) => {
+  try {
+    const user = await createUser(body)
+    return { success: true, user }
+  } catch (e) {
+    return error(400, { success: false, message: e.message })
+  }
+})
+```
+
+## Testing Anti-Patterns
+
+### Never Test Against Real API
+
+```typescript
+// ❌ WRONG - Real API calls in tests
+it('should fetch users', async () => {
+  const { data } = await api.users.get()  // Hits real backend
+  expect(data.users).toBeDefined()
+})
+
+// ✅ CORRECT - Mock Eden Treaty
+vi.mock('@client/lib/eden-api', () => ({
+  api: {
+    users: {
+      get: vi.fn().mockResolvedValue({
+        data: { users: [{ id: 1, name: 'Test' }] },
+        error: undefined
+      })
+    }
+  }
+}))
+```
+
+## Build Anti-Patterns
+
+### Never Import Dev Dependencies in Production
+
+```typescript
+// ❌ WRONG - Conditional import that still bundles
+import { DevTools } from 'react-devtools'  // Always bundled
+
+if (process.env.NODE_ENV === 'development') {
+  DevTools.init()
+}
+
+// ✅ CORRECT - Dynamic import for dev-only
+if (import.meta.env.DEV) {
+  const { DevTools } = await import('react-devtools')
+  DevTools.init()
+}
+```
+
+## Summary Table
+
+| Anti-Pattern | Impact | Solution |
+|-------------|--------|----------|
+| Modifying `core/` | Update conflicts | Use plugins/app |
+| Wrapping Eden Treaty | Lost type inference | Use directly |
+| Missing response schemas | Unknown types | Always define schemas |
+| Direct process.env | No validation | Use config system |
+| Deep relative imports | Fragile paths | Use aliases |
+| NPM plugins without whitelist | Security risk | Set PLUGINS_ALLOWED |
+| Business logic in routes | Unmaintainable | Use controllers |
+
+## Related
+
+- [Project Structure](./project-structure.md)
+- [Type Safety](./type-safety.md)
+- [Plugin Security](../core/plugin-system.md)
+- [Routes with Eden Treaty](../resources/routes-eden.md)

package/LLMD/patterns/project-structure.md

@@ -0,0 +1,264 @@
+# Project Structure
+
+**Version:** 1.11.0 | **Updated:** 2025-02-08
+
+## Quick Facts
+
+- `core/` is **read-only** framework code - NEVER modify
+- `app/` contains all user application code
+- `config/` holds declarative configuration files
+- `plugins/` is for external plugin development
+- Path aliases simplify imports across the project
+
+## Directory Organization
+
+### core/ - Framework Code (READ-ONLY)
+
+**Rule:** NEVER modify files in `core/`
+
+```
+core/
+├── framework/      # Core framework server and lifecycle
+├── plugins/        # Plugin system (manager, registry, types)
+├── server/         # Server utilities (live components, middleware)
+├── client/         # Client-side framework utilities
+├── build/          # Build system and bundling
+├── cli/            # CLI commands and generators
+├── utils/          # Framework utilities
+├── types/          # Framework type definitions
+└── templates/      # Code generation templates
+```
+
+**Why read-only?**
+- Framework updates would overwrite your changes
+- Breaking changes could occur on version upgrades
+- Customization should happen through plugins or app code
+
+**What to do instead:**
+- Create plugins in `plugins/` for framework extensions
+- Override behavior using plugin hooks
+- Implement custom logic in `app/`
+
+### app/ - Application Code (MODIFY HERE)
+
+**Rule:** All your application code goes here
+
+```
+app/
+├── server/         # Backend code
+│   ├── routes/     # API route definitions (Eden Treaty)
+│   ├── controllers/# Business logic and services
+│   ├── live/       # Live component implementations
+│   ├── websockets/ # WebSocket handlers
+│   ├── utils/      # Server-side utilities
+│   ├── app.ts      # Elysia app configuration
+│   └── index.ts    # Server entrypoint
+├── client/         # Frontend code
+│   ├── src/        # React application source
+│   │   ├── components/  # React components
+│   │   ├── pages/       # Page components
+│   │   ├── hooks/       # Custom React hooks
+│   │   ├── stores/      # State management (Zustand)
+│   │   ├── utils/       # Client-side utilities
+│   │   ├── App.tsx      # Root component
+│   │   └── main.tsx     # React entrypoint
+│   ├── public/     # Static assets
+│   └── index.html  # HTML template
+└── shared/         # Shared code between client and server
+    └── types/      # Shared TypeScript types
+```
+
+**Organization principles:**
+- **server/routes/**: Define API endpoints with schemas
+- **server/controllers/**: Implement business logic (keep routes thin)
+- **client/src/**: All React code and frontend logic
+- **shared/types/**: Types used by both frontend and backend
+
+### config/ - Configuration Files
+
+```
+config/
+├── system/              # Framework system configs (rarely modified)
+│   ├── app.config.ts
+│   ├── server.config.ts
+│   ├── client.config.ts
+│   ├── build.config.ts
+│   ├── plugins.config.ts
+│   └── ...
+├── app.config.ts        # Application-specific config
+├── server.config.ts     # Server configuration
+├── client.config.ts     # Client configuration
+├── database.config.ts   # Database configuration
+├── plugins.config.ts    # Plugin configuration
+└── index.ts             # Config aggregator
+```
+
+**Two-tier system:**
+- `config/system/`: Framework defaults (use `defineConfig`)
+- `config/*.config.ts`: User overrides and custom configs
+
+**Best practices:**
+- Override system configs by creating same-named file in `config/`
+- Use `defineConfig` for type safety and validation
+- Keep sensitive values in environment variables
+
+### plugins/ - External Plugins
+
+```
+plugins/
+└── your-plugin/
+    ├── index.ts         # Plugin entrypoint
+    ├── server/          # Server-side plugin code
+    ├── client/          # Client-side plugin code
+    └── package.json     # Plugin metadata
+```
+
+**When to create a plugin:**
+- Reusable functionality across projects
+- Framework extensions (new hooks, middleware)
+- Third-party integrations
+- Shareable with community
+
+**When NOT to use plugins:**
+- Application-specific business logic → use `app/`
+- Simple utilities → use `app/server/utils/` or `app/client/utils/`
+
+## File Naming Conventions
+
+### General Rules
+
+- **kebab-case** for directories: `user-management/`, `auth-service/`
+- **kebab-case** for files: `user-controller.ts`, `auth-utils.ts`
+- **PascalCase** for React components: `UserProfile.tsx`, `LoginForm.tsx`
+- **camelCase** for utility files: `formatDate.ts`, `apiClient.ts`
+
+### Specific Patterns
+
+**Routes:**
+```
+app/server/routes/
+├── users.ts           # /users endpoints
+├── auth.ts            # /auth endpoints
+└── admin/
+    └── dashboard.ts   # /admin/dashboard endpoints
+```
+
+**Controllers:**
+```
+app/server/controllers/
+├── UserController.ts
+├── AuthController.ts
+└── services/
+    ├── UserService.ts
+    └── AuthService.ts
+```
+
+**React Components:**
+```
+app/client/src/components/
+├── UserProfile.tsx
+├── LoginForm.tsx
+└── common/
+    ├── Button.tsx
+    └── Input.tsx
+```
+
+**Types:**
+```
+app/shared/types/
+├── user.types.ts
+├── auth.types.ts
+└── api.types.ts
+```
+
+## Import Path Aliases
+
+**Configured in `tsconfig.json`:**
+
+```typescript
+{
+  "paths": {
+    "@core/*": ["./core/*"],           // Framework code
+    "@app/*": ["./app/*"],             // Application root
+    "@server/*": ["./app/server/*"],   // Server code
+    "@client/*": ["./app/client/*"],   // Client code
+    "@shared/*": ["./app/shared/*"],   // Shared code
+    "@config": ["./config/index.ts"],  // Config aggregator
+    "@config/*": ["./config/*"]        // Individual configs
+  }
+}
+```
+
+### Usage Examples
+
+**Server-side imports:**
+```typescript
+// ✅ Good - Use aliases
+import { UserController } from '@server/controllers/UserController'
+import { UserType } from '@shared/types/user.types'
+import { serverConfig } from '@config'
+
+// ❌ Bad - Relative paths
+import { UserController } from '../../server/controllers/UserController'
+import { UserType } from '../../../shared/types/user.types'
+```
+
+**Client-side imports:**
+```typescript
+// ✅ Good - Use aliases
+import { UserProfile } from '@client/components/UserProfile'
+import { useAuth } from '@client/hooks/useAuth'
+import { UserType } from '@shared/types/user.types'
+
+// ❌ Bad - Relative paths
+import { UserProfile } from '../components/UserProfile'
+import { useAuth } from '../../hooks/useAuth'
+```
+
+**Plugin imports:**
+```typescript
+// ✅ Good - Import from core for plugin development
+import type { FluxStackPlugin } from '@core/types/plugin.types'
+import { logger } from '@core/utils/logger'
+
+// ✅ Good - Import app code if needed
+import { UserType } from '@shared/types/user.types'
+```
+
+### Alias Rules
+
+1. **Always use aliases** for cross-directory imports
+2. **Relative paths OK** for same-directory imports: `./utils`, `./types`
+3. **Never import from `core/`** in app code (except types)
+4. **Use `@shared/*`** for code used by both client and server
+
+## Common Patterns
+
+### Creating a New Feature
+
+1. **Define types** in `app/shared/types/feature.types.ts`
+2. **Create route** in `app/server/routes/feature.ts`
+3. **Implement controller** in `app/server/controllers/FeatureController.ts`
+4. **Build UI** in `app/client/src/pages/FeaturePage.tsx`
+5. **Use Eden Treaty** in client to call API with type safety
+
+### Adding Configuration
+
+1. **Create config file** in `config/feature.config.ts`
+2. **Use `defineConfig`** for schema and validation
+3. **Export from** `config/index.ts`
+4. **Import with** `@config` alias
+
+### Creating a Plugin
+
+1. **Create directory** in `plugins/my-plugin/`
+2. **Implement interface** from `@core/types/plugin.types`
+3. **Add to whitelist** in `config/plugins.config.ts`
+4. **Framework auto-discovers** on startup
+
+## Related
+
+- [Type Safety Patterns](./type-safety.md)
+- [Anti-Patterns](./anti-patterns.md)
+- [Plugin Development](../resources/plugins-external.md)
+- [Configuration System](../config/declarative-system.md)