create-fluxstack 1.19.0 → 1.20.1

package/LLMD/INDEX.md

@@ -1,6 +1,6 @@
 # FluxStack LLM Documentation
 
-**Version:** 2.0.0 | **Framework:** Bun + Elysia + React + Eden Treaty
+**Version:** 1.19.0 | **Framework:** Bun + Elysia + React + Eden Treaty | **Live:** @fluxstack/live 0.7.2
 
 ## Quick Navigation
 

package/LLMD/MAINTENANCE.md

@@ -1,197 +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
+# Documentation Maintenance Guide
+
+**Version:** 1.19.0 | **Updated:** 2026-04-14
+
+## 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

@@ -1,6 +1,6 @@
 # Migration Guide: ai-context/ → LLMD/
 
-**Version:** 1.11.0 | **Updated:** 2025-02-08
+**Version:** 1.19.0 | **Updated:** 2026-04-14
 
 ## Overview
 
@@ -145,6 +145,49 @@ These rules remain the same in both documentation systems:
 - **ALWAYS** use native Eden Treaty: `const { data, error } = await api.users.get()`
 - **ALWAYS** define shared types in `app/shared/`
 
+## Changes v1.12 to v1.19
+
+This section documents the major changes that occurred between v1.12 and v1.19. All LLMD documents have been updated to reflect these changes.
+
+### Plugin-Kit Extraction (v1.19)
+
+- **Auto-discovery removed**: The automatic plugin discovery from `node_modules/` was removed in `@fluxstack/plugin-kit@0.4.0` because it broke silently in production bundles (`dist/node_modules/` does not exist).
+- **Manual registration via `.use()`**: Every plugin the app wants to enable must now be explicitly imported and registered via `.use()` in `app/server/index.ts`.
+- **Project plugins (`plugins/`)**: Also require explicit registration; the `PLUGINS_DISCOVER_PROJECT` env var no longer applies.
+- **Example** (from `app/server/index.ts`):
+  ```typescript
+  import { csrfProtectionPlugin } from "@fluxstack/plugin-csrf-protection"
+
+  const framework = new FluxStackFramework()
+    .use(swaggerPlugin)
+    .use(liveComponentsPlugin)
+    .use(csrfProtectionPlugin)
+  ```
+
+### @fluxstack/live 0.7.2
+
+- **Custom `generateId`**: LiveServer now accepts a custom ID generator function, allowing UUIDs, nanoid, or any other strategy.
+- **WebSocket optimizations**: Reduced overhead on message encoding/decoding and improved reconnection logic.
+
+### Reactive State Proxy (v1.12)
+
+- State mutations auto-sync with the frontend via Proxy.
+- `this.state.count++` triggers a `STATE_DELTA` automatically.
+- `setState()` remains available for batch updates (multiple properties in a single emit).
+
+### Static defaultState (v1.12)
+
+- `defaultState` is now defined inside the class as a static property.
+- Old pattern (`export const defaultState = {...}` outside the class) is deprecated.
+- Less boilerplate, better encapsulation.
+
+### Theme System (v1.18)
+
+- Built-in theme support for the frontend with light/dark mode.
+- Theme configuration via `config/client.config.ts`.
+
+---
+
 ## Feedback
 
 If you find outdated content or missing information in `LLMD/`, please update the relevant document and increment the update date.

package/LLMD/agent.md

@@ -1,6 +1,6 @@
 # FluxStack Agent Guide
 
-**Version:** 1.13.0 | **Updated:** 2025-02-14
+**Version:** 1.19.0 | **Updated:** 2026-04-14
 
 > Guia completo para agentes de IA que auxiliam desenvolvedores a configurar, construir e manter aplicacoes FluxStack.
 
@@ -44,7 +44,7 @@ FluxStack/
 ├── config/         # CONFIGURACOES (declarativas, com validacao)
 │   ├── system/     #   Defaults do framework (base)
 │   └── *.config.ts #   Overrides do usuario
-├── plugins/        # PLUGINS DO PROJETO (auto-discovered, confiaveis)
+├── plugins/        # PLUGINS DO PROJETO (registro manual via .use())
 ├── tests/          # TESTES (Vitest)
 └── LLMD/           # DOCUMENTACAO LLM-optimizada
 ```
@@ -420,7 +420,20 @@ const meuPlugin: FluxStackPlugin = {
 export default meuPlugin
 ```
 
-Plugins em `plugins/` sao auto-discovered e confiaveis. Nao precisam de whitelist.
+**Passo 3 - Registrar o plugin** em `app/server/index.ts`:
+
+Desde v1.19 (plugin-kit 0.4.0), todos os plugins devem ser registrados manualmente via `.use()`.
+Nao existe mais auto-discovery de plugins. Importe e registre explicitamente:
+
+```typescript
+// app/server/index.ts
+import meuPlugin from '../../plugins/meu-plugin'
+
+const framework = new FluxStackFramework()
+  .use(swaggerPlugin)
+  .use(liveComponentsPlugin)
+  .use(meuPlugin)           // <-- registro explicito
+```
 
 ---
 
@@ -718,7 +731,7 @@ bun run flux plugin:remove nome-plugin # Remover plugin
 3. **Omitir response schemas** - Eden Treaty perde a tipagem no frontend
 4. **Usar `process.env` diretamente** - Use o sistema de config declarativo
 5. **Colocar logica de negocio em rotas** - Use controllers/services
-6. **Habilitar NPM discovery sem whitelist** - Risco de supply chain attack
+6. **Usar plugins sem registro explicito via .use()** - Auto-discovery foi removida em v1.19
 7. **Criar tipos manuais para respostas de API** - Eden Treaty infere automaticamente
 8. **Usar imports relativos profundos** - Use path aliases (@server, @client, etc.)
 9. **Armazenar dados nao-serializaveis no state de Live Components**
@@ -765,9 +778,9 @@ Live Component nao sincroniza?
 │       └── SIM → State e serializavel (sem functions, Date, etc.)?
 
 Plugin nao carrega?
-├── E plugin NPM?
-│   ├── SIM → PLUGINS_DISCOVER_NPM=true e PLUGINS_ALLOWED configurado?
-│   └── NAO → Esta em plugins/ com export default?
+├── Foi importado e registrado via .use() em app/server/index.ts?
+│   ├── NAO → Importar e registrar com framework.use(meuPlugin)
+│   └── SIM → Export default esta correto no index.ts do plugin?
 └── Verificar logs de seguranca no console
 
 Config nao carrega?