create-fluxstack 1.10.1 → 1.12.0

package/.dockerignore

@@ -48,9 +48,8 @@ docs/
 # Development tools
 .eslintrc*
 .prettierrc*
-tsconfig*.json
 vitest.config.ts
-vite.config.ts
+# Note: tsconfig.json is needed for Bun path alias resolution during build
 
 # OS files
 .DS_Store

package/Dockerfile

@@ -1,10 +1,10 @@
-# 🐳 FluxStack Production Dockerfile
+# FluxStack Production Dockerfile
 # Multi-stage build for optimized production image
 
 # =====================================
 # Stage 1: Dependencies
 # =====================================
-FROM oven/bun:1.1.34-alpine AS deps
+FROM oven/bun:1.2-alpine AS deps
 
 WORKDIR /app
 
@@ -17,7 +17,7 @@ RUN bun install --production --frozen-lockfile
 # =====================================
 # Stage 2: Builder
 # =====================================
-FROM oven/bun:1.1.34-alpine AS builder
+FROM oven/bun:1.2-alpine AS builder
 
 WORKDIR /app
 
@@ -34,7 +34,7 @@ RUN bun run build
 # =====================================
 # Stage 3: Production Runner
 # =====================================
-FROM oven/bun:1.1.34-alpine AS runner
+FROM oven/bun:1.2-alpine AS runner
 
 WORKDIR /app
 
@@ -62,9 +62,9 @@ USER fluxstack
 # Expose application port
 EXPOSE 3000
 
-# Health check disabled for now
-# HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
-#   CMD bun run -e 'fetch("http://localhost:3000/api/health").then(r => r.ok ? process.exit(0) : process.exit(1))' || exit 1
+# Health check for container orchestrators
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD bun -e 'fetch("http://localhost:3000/api/health").then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))'
 
 # Start the application
-CMD ["bun", "run", "start"]
+CMD ["bun", "dist/index.js"]

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