create-fluxstack 1.9.1 → 1.12.0

package/LLMD/INDEX.md

@@ -0,0 +1,64 @@
+# FluxStack LLM Documentation
+
+**Version:** 1.12.0 | **Framework:** Bun + Elysia + React + Eden Treaty
+
+## Quick Navigation
+
+**First Time?** → [core/framework-lifecycle.md](core/framework-lifecycle.md)
+**Creating Routes?** → [resources/routes-eden.md](resources/routes-eden.md)
+**Real-time Rooms?** → [resources/live-rooms.md](resources/live-rooms.md)
+**Config Issues?** → [config/declarative-system.md](config/declarative-system.md)
+**Plugin Development?** → [resources/plugins-external.md](resources/plugins-external.md)
+**Errors?** → [reference/troubleshooting.md](reference/troubleshooting.md)
+
+## Core Concepts
+
+- [Framework Lifecycle](core/framework-lifecycle.md) - Startup, request handling, shutdown
+- [Plugin System](core/plugin-system.md) - Architecture, hooks, load order
+- [Build System](core/build-system.md) - Dev vs production builds
+
+## Configuration
+
+- [Declarative System](config/declarative-system.md) - defineConfig, validation, types
+- [Environment Variables](config/environment-vars.md) - Complete reference
+- [Runtime Reload](config/runtime-reload.md) - Hot config updates
+
+## Creating Resources
+
+- [Routes with Eden Treaty](resources/routes-eden.md) - Type-safe API routes
+- [Controllers & Services](resources/controllers.md) - Business logic patterns
+- [Live Components](resources/live-components.md) - WebSocket components
+- [Live Rooms](resources/live-rooms.md) - Multi-room real-time communication
+- [Live Upload](resources/live-upload.md) - Chunked upload via Live Components
+- [External Plugins](resources/plugins-external.md) - Plugin development
+- [Routing (React Router v7)](reference/routing.md) - Frontend routing setup
+
+## Patterns & Rules
+
+- [Project Structure](patterns/project-structure.md) - Folder organization
+- [Type Safety](patterns/type-safety.md) - Eden Treaty type flow
+- [Anti-Patterns](patterns/anti-patterns.md) - What NOT to do
+
+## Reference
+
+- [CLI Commands](reference/cli-commands.md) - Complete command reference
+- [Plugin Hooks](reference/plugin-hooks.md) - All available hooks
+- [Troubleshooting](reference/troubleshooting.md) - Common issues
+
+## Critical Rules
+
+**NEVER:**
+- Modify files in `core/` (framework is read-only)
+- Wrap Eden Treaty in custom functions
+- Omit response schemas in routes
+
+**ALWAYS:**
+- Work in `app/` directory
+- Use native Eden Treaty: `const { data, error } = await api.users.get()`
+- Define shared types in `app/shared/`
+- Run `bun run dev` after changes
+
+## Migration & Maintenance
+
+- [MIGRATION.md](MIGRATION.md) - Changes from `ai-context/` to `LLMD/`
+- [MAINTENANCE.md](MAINTENANCE.md) - How to update this documentation

package/LLMD/MAINTENANCE.md

@@ -0,0 +1,197 @@
+# Documentation Maintenance Guide
+
+**Version:** 1.11.0 | **Updated:** 2025-02-08
+
+## Quick Facts
+
+- Documentation lives in `/LLMD/`
+- Each document tracks version and update date
+- Target: <2000 tokens per document
+- All internal links must be validated
+
+## Document Format
+
+Every document follows this template:
+
+```markdown
+# Document Title
+
+**Version:** X.Y.Z | **Updated:** YYYY-MM-DD
+
+## Quick Facts
+
+- Key point 1
+- Key point 2
+
+## [Main Sections]
+
+Content...
+
+## Related
+
+- [Link 1](./path.md)
+- [Link 2](./path.md)
+```
+
+## When to Update Documentation
+
+### Code Changes That Require Doc Updates
+
+| Change Type | Update Required |
+|-------------|-----------------|
+| New CLI command | `reference/cli-commands.md` |
+| New plugin hook | `reference/plugin-hooks.md`, `core/plugin-system.md` |
+| New config option | `config/environment-vars.md`, `config/declarative-system.md` |
+| Changed API pattern | `resources/routes-eden.md`, `patterns/type-safety.md` |
+| New framework feature | Relevant `core/*.md` file |
+| Build system change | `core/build-system.md` |
+| Breaking change | `patterns/anti-patterns.md`, `reference/troubleshooting.md` |
+
+### Version Bump Checklist
+
+When FluxStack version changes:
+
+1. Update `**Version:**` header in all `.md` files
+2. Update `MIGRATION.md` if needed
+3. Add new entries to `reference/troubleshooting.md` for version-specific issues
+4. Update `INDEX.md` if new documents added
+
+## Adding New Documentation
+
+### New Document Checklist
+
+1. **Create file** in appropriate directory:
+   - `core/` - Framework internals
+   - `config/` - Configuration system
+   - `resources/` - Creating things (routes, controllers, plugins)
+   - `patterns/` - Best practices and rules
+   - `reference/` - Quick lookup (CLI, hooks, troubleshooting)
+
+2. **Add header** with version and date
+
+3. **Add to INDEX.md** in the right section
+
+4. **Add Related links** at bottom of new document
+
+5. **Cross-link** from related existing documents
+
+### Token Efficiency Guidelines
+
+- No prose introductions ("In this document we will...")
+- Use tables for reference data
+- Use code blocks, not explanations of code
+- Bullet points over paragraphs
+- No repeated information (link instead)
+
+## Link Validation
+
+### Manual Check
+
+```bash
+# Find all internal links
+grep -r "\]\(./" LLMD/ | grep "\.md"
+
+# Verify each path exists
+```
+
+### Required Links to Check
+
+Each document should have working links in:
+- `## Related` section at bottom
+- Any inline references
+
+## Directory Structure
+
+```
+LLMD/
+├── INDEX.md              # Navigation hub (update for new docs)
+├── MIGRATION.md          # Changes from ai-context/
+├── MAINTENANCE.md        # This file
+├── core/
+│   ├── framework-lifecycle.md
+│   ├── plugin-system.md
+│   └── build-system.md
+├── config/
+│   ├── declarative-system.md
+│   ├── environment-vars.md
+│   └── runtime-reload.md
+├── resources/
+│   ├── routes-eden.md
+│   ├── controllers.md
+│   ├── live-components.md
+│   └── plugins-external.md
+├── patterns/
+│   ├── project-structure.md
+│   ├── type-safety.md
+│   └── anti-patterns.md
+└── reference/
+    ├── cli-commands.md
+    ├── plugin-hooks.md
+    └── troubleshooting.md
+```
+
+## Code Example Standards
+
+### TypeScript Examples
+
+```typescript
+// ✅ Include imports when non-obvious
+import { Elysia, t } from 'elysia'
+
+// ✅ Show complete, runnable snippets
+export const route = new Elysia()
+  .get('/', () => ({ status: 'ok' }))
+```
+
+### Bash Examples
+
+```bash
+# ✅ Include expected output when helpful
+bun run dev
+# ⚡ Starting Full-stack development server...
+# Backend: http://localhost:3000
+# Frontend: http://localhost:5173
+```
+
+### Avoid
+
+```typescript
+// ❌ Incomplete snippets
+.get('/', () => ...)
+
+// ❌ Unexplained magic
+const x = doSomething() // What is doSomething?
+```
+
+## Sync with Code Changes
+
+### Before PR
+
+1. Check if code changes affect documentation
+2. Update relevant documents
+3. Update version dates
+4. Validate links
+
+### After Major Feature
+
+1. Create new document if needed
+2. Update INDEX.md
+3. Add to MIGRATION.md for notable changes
+4. Cross-reference from related docs
+
+## Quality Checklist
+
+Before committing documentation changes:
+
+- [ ] Version and date updated
+- [ ] All code examples syntactically valid
+- [ ] All internal links work
+- [ ] No duplicate information (link instead)
+- [ ] Added to INDEX.md if new document
+- [ ] Related section has relevant links
+- [ ] Token count reasonable (<2000 target)
+
+## Related
+
+- [INDEX.md](./INDEX.md) - Main navigation
+- [MIGRATION.md](./MIGRATION.md) - Version changes

package/LLMD/MIGRATION.md

@@ -0,0 +1,156 @@
+# Migration Guide: ai-context/ → LLMD/
+
+**Version:** 1.11.0 | **Updated:** 2025-02-08
+
+## Overview
+
+This document explains the migration from the old `ai-context/` documentation structure to the new `LLMD/` (LLM Documentation) structure. The new system is optimized for token efficiency, direct information access, and accurate reflection of the current codebase.
+
+## Key Changes
+
+### Philosophy Shift
+
+**Old (`ai-context/`):**
+- Mixed Portuguese and English content
+- Verbose explanations with context
+- Scattered information across multiple files
+- Some outdated content from v1.9
+
+**New (`LLMD/`):**
+- English-only for consistency
+- Direct, technical language without fluff
+- Modular organization by domain
+- Reflects current v1.11.0 codebase
+- Single entrypoint (INDEX.md) for quick navigation
+
+### Directory Structure Mapping
+
+| Old Location | New Location | Notes |
+|-------------|--------------|-------|
+| `ai-context/00-QUICK-START.md` | `LLMD/INDEX.md` | Now a navigation hub |
+| `ai-context/project/overview.md` | `LLMD/core/framework-lifecycle.md` | More detailed lifecycle |
+| `ai-context/project/architecture.md` | `LLMD/core/plugin-system.md` | Split into focused docs |
+| `ai-context/project/configuration.md` | `LLMD/config/declarative-system.md` | Expanded config docs |
+| `ai-context/project/build-pipeline.md` | `LLMD/core/build-system.md` | Updated for v1.11.0 |
+| `ai-context/development/patterns.md` | `LLMD/patterns/project-structure.md` | Split by topic |
+| `ai-context/development/eden-treaty-guide.md` | `LLMD/resources/routes-eden.md` | Focused on route creation |
+| `ai-context/development/plugins-guide.md` | `LLMD/resources/plugins-external.md` | Plugin development only |
+| `ai-context/development/live-components.md` | `LLMD/resources/live-components.md` | Maintained |
+| `ai-context/development/monitoring.md` | *(Removed)* | Not core framework feature |
+| `ai-context/reference/environment-vars.md` | `LLMD/config/environment-vars.md` | Comprehensive table format |
+| `ai-context/reference/cli-commands.md` | `LLMD/reference/cli-commands.md` | Complete command reference |
+| `ai-context/reference/config-api.md` | `LLMD/config/runtime-reload.md` | Focused on reload mechanism |
+| `ai-context/reference/troubleshooting.md` | `LLMD/reference/troubleshooting.md` | Updated for v1.11.0 |
+| `ai-context/examples/crud-complete.md` | *(Integrated)* | Examples now inline in docs |
+| `ai-context/recent-changes/` | *(Removed)* | Version tracking in each doc |
+
+## Content Changes
+
+### What's New in LLMD/
+
+1. **Plugin Hooks Reference** (`reference/plugin-hooks.md`)
+   - Complete hook reference table
+   - Execution order documentation
+   - Hook context interfaces
+
+2. **Type Safety Patterns** (`patterns/type-safety.md`)
+   - Eden Treaty type flow diagrams
+   - Type inference examples
+   - Common type issues
+
+3. **Anti-Patterns** (`patterns/anti-patterns.md`)
+   - Common mistakes and violations
+   - What NOT to do
+   - Framework rules enforcement
+
+4. **Runtime Configuration** (`config/runtime-reload.md`)
+   - ReactiveConfig usage
+   - Hot reload mechanism
+   - Watch callbacks
+
+5. **Controllers Pattern** (`resources/controllers.md`)
+   - Business logic separation
+   - Service layer patterns
+   - Error handling
+
+### What's Removed
+
+- **Monitoring documentation**: Not a core framework feature (plugin-specific)
+- **Recent changes directory**: Version tracking now in each document
+- **Verbose examples**: Replaced with minimal, inline examples
+- **Portuguese content**: All content now in English
+
+### What's Updated
+
+- **Version**: All docs reflect v1.11.0
+- **Code examples**: Validated against current codebase
+- **Environment variables**: Complete and accurate list
+- **CLI commands**: All current commands documented
+- **Plugin system**: Updated with latest architecture
+
+## Migration Timeline
+
+### Phase 1: Coexistence (Current)
+- Both `ai-context/` and `LLMD/` exist
+- `ai-context/` marked as deprecated
+- New content goes to `LLMD/`
+
+### Phase 2: Transition (Future)
+- Update all references to point to `LLMD/`
+- Add redirects in `ai-context/` files
+- Keep `ai-context/` for reference
+
+### Phase 3: Deprecation (Future)
+- Archive `ai-context/` to separate branch
+- Remove from main branch
+- `LLMD/` becomes primary documentation
+
+## How to Use LLMD/
+
+### For LLMs
+
+1. **Start with INDEX.md**: Single entrypoint with navigation
+2. **Load only what you need**: Modular files save tokens
+3. **Check version**: Each doc includes version and update date
+4. **Follow links**: Related docs are cross-referenced
+
+### For Developers
+
+1. **Quick reference**: INDEX.md has all critical rules
+2. **Deep dive**: Follow links to specific topics
+3. **Troubleshooting**: reference/troubleshooting.md for common issues
+4. **Examples**: Inline examples in each resource doc
+
+## Quick Reference Mapping
+
+### Common Tasks
+
+| Task | Old Path | New Path |
+|------|----------|----------|
+| Create a route | `development/eden-treaty-guide.md` | `resources/routes-eden.md` |
+| Configure app | `project/configuration.md` | `config/declarative-system.md` |
+| Create plugin | `development/plugins-guide.md` | `resources/plugins-external.md` |
+| Fix errors | `reference/troubleshooting.md` | `reference/troubleshooting.md` |
+| Understand lifecycle | `project/architecture.md` | `core/framework-lifecycle.md` |
+| CLI commands | `reference/cli-commands.md` | `reference/cli-commands.md` |
+
+### Critical Rules (Unchanged)
+
+These rules remain the same in both documentation systems:
+
+- **NEVER** modify files in `core/` (framework is read-only)
+- **NEVER** wrap Eden Treaty in custom functions
+- **NEVER** omit response schemas in routes
+- **ALWAYS** work in `app/` directory
+- **ALWAYS** use native Eden Treaty: `const { data, error } = await api.users.get()`
+- **ALWAYS** define shared types in `app/shared/`
+
+## Feedback
+
+If you find outdated content or missing information in `LLMD/`, please update the relevant document and increment the update date.
+
+## Related Documents
+
+- [INDEX.md](INDEX.md) - Main navigation hub
+- [requirements.md](../.kiro/specs/llm-docs-refactor/requirements.md) - Requirements for this refactor
+- [design.md](../.kiro/specs/llm-docs-refactor/design.md) - Design decisions

package/LLMD/config/.gitkeep

@@ -0,0 +1 @@
+# Configuration documentation directory

package/LLMD/config/declarative-system.md

@@ -0,0 +1,268 @@
+# Declarative Configuration System
+
+**Version:** 1.11.0 | **Updated:** 2025-02-08
+
+## Quick Facts
+
+- Laravel-inspired schema-based configuration with automatic validation
+- Type-safe config with full TypeScript inference
+- Environment variable mapping with type casting
+- Runtime reload support via `ReactiveConfig`
+- Located in `config/system/*.config.ts`
+- Core implementation: `core/utils/config-schema.ts`
+
+## defineConfig Function
+
+Creates a static configuration object from a schema:
+
+```typescript
+import { defineConfig, config } from '@core/utils/config-schema'
+
+const appConfig = defineConfig({
+  name: config.string('APP_NAME', 'MyApp', true),
+  port: config.number('PORT', 3000, true),
+  env: config.enum('NODE_ENV', ['development', 'production'] as const, 'development')
+})
+
+// Type-safe access
+appConfig.name  // string
+appConfig.port  // number
+appConfig.env   // "development" | "production"
+```
+
+## ConfigField Types
+
+### string
+
+```typescript
+{
+  type: 'string',
+  env: 'VAR_NAME',
+  default: 'value',
+  required: false
+}
+
+// Shorthand
+config.string('VAR_NAME', 'default', required)
+```
+
+### number
+
+```typescript
+{
+  type: 'number',
+  env: 'PORT',
+  default: 3000,
+  required: true,
+  validate: (value) => value > 0 && value < 65536
+}
+
+// Shorthand
+config.number('PORT', 3000, true)
+```
+
+Casts string env vars to numbers automatically.
+
+### boolean
+
+```typescript
+{
+  type: 'boolean',
+  env: 'ENABLE_FEATURE',
+  default: false
+}
+
+// Shorthand
+config.boolean('ENABLE_FEATURE', false)
+```
+
+Accepts: `true`, `1`, `yes`, `on` (case-insensitive) as true.
+
+### array
+
+```typescript
+{
+  type: 'array',
+  env: 'ALLOWED_HOSTS',
+  default: ['localhost']
+}
+
+// Shorthand
+config.array('ALLOWED_HOSTS', ['localhost'])
+```
+
+Parses comma-separated strings: `"host1,host2,host3"` → `['host1', 'host2', 'host3']`
+
+### object
+
+```typescript
+{
+  type: 'object',
+  env: 'METADATA',
+  default: {}
+}
+```
+
+Parses JSON strings from env vars.
+
+### enum
+
+```typescript
+{
+  type: 'enum',
+  env: 'NODE_ENV',
+  values: ['development', 'production', 'test'] as const,
+  default: 'development',
+  validate: (value) => value !== 'test' || 'Test mode not allowed'
+}
+
+// Shorthand
+config.enum('NODE_ENV', ['development', 'production'] as const, 'development')
+```
+
+Validates value is in allowed list. TypeScript infers union type.
+
+## Validation
+
+### Built-in Validation
+
+- **Required fields**: Throws error if missing
+- **Type casting**: Automatic conversion from env strings
+- **Enum validation**: Ensures value in allowed list
+
+### Custom Validation
+
+```typescript
+{
+  type: 'number',
+  env: 'PORT',
+  default: 3000,
+  validate: (value: number) => {
+    if (value < 1 || value > 65535) {
+      return 'Port must be between 1 and 65535'
+    }
+    return true
+  }
+}
+```
+
+Return `true` for valid, `false` or error string for invalid.
+
+### Validation Errors
+
+```typescript
+// Throws on startup if validation fails:
+// ❌ Configuration validation failed:
+//   - Field 'port' is required but not provided
+//   - Field 'env' must be one of: development, production (got: "staging")
+```
+
+## ReactiveConfig (Runtime Reload)
+
+For configs that need runtime updates:
+
+```typescript
+import { defineReactiveConfig } from '@core/utils/config-schema'
+
+const reactiveConfig = defineReactiveConfig({
+  feature: config.boolean('FEATURE_FLAG', false)
+})
+
+// Access values
+reactiveConfig.values.feature  // false
+
+// Watch for changes
+const unwatch = reactiveConfig.watch((newConfig) => {
+  console.log('Config updated:', newConfig.feature)
+})
+
+// Reload from environment
+reactiveConfig.reload()
+
+// Stop watching
+unwatch()
+```
+
+See [runtime-reload.md](./runtime-reload.md) for detailed usage.
+
+## Nested Configuration
+
+Group related configs:
+
+```typescript
+import { defineNestedConfig } from '@core/utils/config-schema'
+
+const serverConfig = defineNestedConfig({
+  server: {
+    port: config.number('PORT', 3000),
+    host: config.string('HOST', 'localhost')
+  },
+  cors: {
+    origins: config.array('CORS_ORIGINS', ['http://localhost:3000']),
+    credentials: config.boolean('CORS_CREDENTIALS', false)
+  }
+})
+
+// Access nested
+serverConfig.server.port    // 3000
+serverConfig.cors.origins   // ['http://localhost:3000']
+```
+
+## Helper Functions
+
+```typescript
+import { config } from '@core/utils/config-schema'
+
+// All helpers: (envVar, default, required)
+config.string('VAR', 'default', false)
+config.number('VAR', 42, true)
+config.boolean('VAR', false)
+config.array('VAR', ['item'])
+config.enum('VAR', ['a', 'b'] as const, 'a')
+```
+
+## Custom Transformers
+
+Apply custom logic before validation:
+
+```typescript
+{
+  type: 'string',
+  env: 'API_URL',
+  default: 'http://localhost:3000',
+  transform: (value) => value.endsWith('/') ? value.slice(0, -1) : value
+}
+```
+
+## Configuration Files
+
+All system configs in `config/system/`:
+
+- `app.config.ts` - Application metadata
+- `server.config.ts` - Server and CORS settings
+- `client.config.ts` - Frontend configuration
+- `build.config.ts` - Build settings
+- `database.config.ts` - Database connection
+- `plugins.config.ts` - Plugin system settings
+- `services.config.ts` - External services
+- `monitoring.config.ts` - Logging and metrics
+
+## Type Inference
+
+Full TypeScript type safety:
+
+```typescript
+const config = defineConfig({
+  port: config.number('PORT', 3000),
+  env: config.enum('NODE_ENV', ['dev', 'prod'] as const, 'dev')
+})
+
+// Inferred types:
+config.port  // number
+config.env   // "dev" | "prod"
+```
+
+## Related
+
+- [Environment Variables](./environment-vars.md) - Complete env var reference
+- [Runtime Reload](./runtime-reload.md) - ReactiveConfig usage patterns