create-fluxstack 1.18.1 → 1.20.0

package/LLMD/patterns/project-structure.md

@@ -1,264 +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)
+# Project Structure
+
+**Version:** 1.19.0 | **Updated:** 2026-04-14
+
+## 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)

package/LLMD/patterns/type-safety.md

@@ -1,6 +1,6 @@
 # Type Safety Patterns
 
-**Version:** 1.11.0 | **Updated:** 2025-02-08
+**Version:** 1.19.0 | **Updated:** 2026-04-14
 
 ## Quick Facts
 
@@ -65,18 +65,22 @@ export const usersRoutes = new Elysia({ prefix: '/users' })
 **Step 2: Use Eden Treaty client**
 
 ```typescript
-// app/client/src/lib/api.ts
-import { createEdenClient } from '@core/client/api/eden'
+// app/client/src/lib/eden-api.ts
+import { createEdenClient, getErrorMessage } from '@/core/client/api'
 import type { App } from '@server/app'
 
-export const api = createEdenClient<App>()
+export const api = createEdenClient<App>({
+  // Optional customization: tokenKey, getAuthToken, onUnauthorized, getBaseUrl, enableLogging
+})
+
+export { getErrorMessage }
 ```
 
 **Step 3: Make typed API calls**
 
 ```typescript
 // app/client/src/pages/UsersPage.tsx
-import { api } from '@/lib/api'
+import { api } from '@/lib/eden-api'
 
 async function loadUsers() {
   const { data, error } = await api.users.get()
@@ -215,6 +219,58 @@ const { data } = await api.users.get({
 //    ^? { users: User[], page: number, limit: number, total: number } | undefined
 ```
 
+### Discriminated Union with t.Union
+
+The real codebase uses `t.Union` for routes that return different shapes depending on success/failure. See `app/server/routes/users.routes.ts` for the canonical example:
+
+```typescript
+// Backend — discriminated union response schema
+const CreateUserResponseSchema = t.Union([
+  t.Object({
+    success: t.Literal(true),
+    user: UserSchema,
+    message: t.Optional(t.String())
+  }),
+  t.Object({
+    success: t.Literal(false),
+    error: t.String()
+  })
+], {
+  description: 'Response after attempting to create a user'
+})
+
+// Route with per-status-code responses
+.post('/', async ({ body, set }) => {
+  const result = await UsersController.createUser(body)
+  if (!result.success) {
+    set.status = 409
+    return result
+  }
+  set.status = 201
+  return result
+}, {
+  body: CreateUserRequestSchema,
+  response: {
+    201: CreateUserResponseSchema,
+    400: t.Object({ success: t.Literal(false), error: t.String() }),
+    409: t.Object({ success: t.Literal(false), error: t.String() })
+  }
+})
+
+// Frontend — TypeScript narrows via the discriminant field
+const { data, error } = await api.users.post({
+  name: 'Jane', email: 'jane@example.com'
+})
+
+if (data?.success) {
+  console.log(data.user.name)   // TS knows `user` exists
+} else if (data) {
+  console.error(data.error)     // TS knows `error` exists
+}
+```
+
+**Key takeaway:** Define `t.Union([...])` at the schema level (not just multiple status codes) so Eden Treaty infers a proper discriminated union type on the client. Use `t.Literal(true)` / `t.Literal(false)` on a shared field (like `success`) so TypeScript can narrow the type with a simple `if` check.
+
 ## Shared Types
 
 For types used across client and server, define in `app/shared/types/`:

package/LLMD/reference/cli-commands.md

@@ -1,6 +1,6 @@
 # CLI Commands Reference
 
-**Version:** 1.11.0 | **Updated:** 2025-02-08
+**Version:** 1.19.0 | **Updated:** 2026-04-14
 
 ## Quick Facts
 
@@ -227,12 +227,36 @@ bun run flux help generate
 Standard npm scripts in `package.json`:
 
 ```bash
-bun run dev           # flux dev
-bun run build         # flux build
-bun run start         # NODE_ENV=production bun dist/server/index.js
-bun run test          # vitest
-bun run lint          # eslint
-bun run typecheck     # tsc --noEmit
+# Development
+bun run dev              # Full-stack dev (backend + frontend)
+bun run dev:frontend     # Frontend only (Vite, port 5173)
+bun run dev:backend      # Backend only (Elysia)
+
+# Build
+bun run build            # Full production build (frontend + backend)
+bun run build:frontend   # Frontend build only
+bun run build:backend    # Backend build only
+bun run build:exe        # Build + compile to executable
+
+# Production
+bun run start            # NODE_ENV=production bun dist/index.js
+
+# Testing
+bun run test             # vitest (watch mode)
+bun run test:ui          # vitest with browser UI (--ui)
+bun run test:coverage    # vitest run with coverage report
+bun run test:e2e         # Playwright end-to-end tests
+bun run test:e2e:ui      # Playwright with interactive UI
+bun run test:e2e:headed  # Playwright in headed browser mode
+
+# Code Quality
+bun run typecheck:api    # Type-check API routes (tsconfig.api-strict.json)
+
+# Generators & Utilities
+bun run make:component   # Scaffold a new component via CLI
+bun run sync-version     # Sync version across package.json and version.ts
+bun run cli              # Direct access to FluxStack CLI
+bun run create           # Create new FluxStack project
 ```
 
 ## Environment Variables for CLI