create-fluxstack 1.18.1 → 1.20.0

package/CHANGELOG.md

@@ -2,6 +2,138 @@
 
 All notable changes to FluxStack will be documented in this file.
 
+## [1.19.0] - 2026-04-11
+
+### Major Refactor: Plugin System Extracted to `@fluxstack/plugin-kit`
+
+The plugin system (manager, registry, executor, discovery, dependency
+manager, module resolver, types) has been extracted from `core/plugins/`
+into the new standalone package `@fluxstack/plugin-kit`. This is the
+same playbook we used for `@fluxstack/live` in 1.16.0 — implementation
+lives in the lib, `core/plugins/` is now a thin re-export shim layer
+for backwards compatibility with existing `@core/plugins/*` imports.
+
+**Impact:** ~3,300 lines of plugin system implementation deleted from
+the app, `core/plugins/` went from 9 runtime files (4017 lines) to
+2 thin shims (types.ts + index.ts, ~200 lines combined). Single
+source of truth for plugin types and runtime is now
+`@fluxstack/plugin-kit`.
+
+### Breaking Changes
+
+- **Auto-discovery removed from `PluginManager.initialize()`** (plugin-kit 0.4.0).
+  The old code called `readdir('node_modules')` and `readdir('plugins')`
+  at startup to discover plugins. This silently broke in production
+  bundles where those directories don't exist, and prevented bundlers
+  from statically including plugin code. Host apps must now register
+  plugins explicitly via `framework.use(pluginObject)`. Dev and prod
+  are now identical; the bundler can tree-shake.
+
+- **`PluginManager` constructor requires `settings` and `clientHooks`**
+  explicitly. These used to be read from the full config / imported
+  as module-level singletons. Now they're injected:
+  ```ts
+  new PluginManager<FluxStackConfig>({
+    config: fullConfig,
+    settings: fullConfig.plugins,
+    logger: pluginLogger,
+    clientHooks: { register: (...) => pluginClientHooks.register(...) },
+    app: this.app,
+  })
+  ```
+
+- **`FluxStack.Plugin` generic over `TConfig`**. The legacy form
+  (no generic) still works and defaults to `unknown`. FluxStack's
+  shim specializes to `Plugin<FluxStackConfig>`.
+
+- **Plugin classes discouraged, object literals are canonical**.
+  All built-in plugins and `@fluxstack/plugin-csrf-protection` use
+  `export const xxxPlugin: Plugin = { name, setup, ... }`. The
+  `class X implements Plugin` form is retired from the generators
+  but still technically accepted at runtime (it implements the
+  same interface).
+
+### Added
+
+- **`@fluxstack/plugin-kit`** — new npm package. Types + runtime
+  for the plugin system. Published at 0.4.0 as of this release.
+  Used by FluxStack app and external plugin packages alike.
+- **`tests/integration/framework/registered-plugins.test.ts`** (10 tests)
+  — end-to-end verification that the four plugins registered via
+  `framework.use()` in `app/server/index.ts` actually inject their
+  hooks at runtime. Catches the class of bug where plugin objects
+  are registered but no hook actually fires (the exact failure
+  mode of the old auto-discovery in prod bundles).
+- **Static plugin registration everywhere**. `app/server/index.ts`
+  now imports `csrfProtectionPlugin` from `@fluxstack/plugin-csrf-protection`
+  directly and registers via `.use()`. Same pattern as the built-ins.
+- **Startup banner reads from the PluginRegistry**. The banner line
+  `Plugins (N): ...` now lists exactly what `framework.getPluginRegistry().getAll()`
+  returns, instead of relying on each plugin manually pushing itself
+  to `globalThis.__fluxstackPlugins`. Backwards compatible — the old
+  global is still read as a fallback.
+- **`@fluxstack/sdk` deprecated on npm** with a message pointing
+  users to `@fluxstack/plugin-kit`. The SDK was a static copy of
+  plugin types + a duplicate of `@fluxstack/config`; both have
+  canonical sources now.
+- **`make:plugin` CLI** generates plain object literal plugins
+  importing from `@fluxstack/plugin-kit`. Identifier generation
+  fixed: `my-plugin` → `myPlugin` (not `myPluginPlugin`).
+
+### Changed
+
+- **`@fluxstack/live` family bumped** from `^0.6.0` to `^0.7.1`.
+  Ships three follow-up bug fixes: opt-in `includeSelf` on `$room`
+  proxy emit (#15), `deepAssign` clones plain objects to break
+  external aliasing (#13), fail-loud protocol framing + telemetry (#7).
+- **`create-fluxstack` README template**: removed the `loggerPlugin`
+  example (that plugin was deleted), replaced class-based plugin
+  example with object literal, added a hook reference table.
+- **`plugins/README.md` template**: rewritten to reflect the static
+  `.use()` model. Explicitly calls out that plugins are NOT
+  auto-discovered. Points at `@fluxstack/plugin-csrf-protection`
+  as the living reference implementation.
+- **Bundle prod size** grew from ~2.46 MB to ~3.34 MB because
+  `@fluxstack/plugin-csrf-protection` is now statically included.
+  Before, it was dynamically loaded via `readdir('node_modules')`
+  and the bundler couldn't see it.
+- **Vite plugin startup banner label fixed** — `| Vite: embedded`
+  only shows in development now. In production the vite plugin
+  runs in static-fallback mode (serving `dist/client/`) and doesn't
+  actually run a Vite dev server, so the label was misleading.
+
+### Removed
+
+- **6934 lines of dead test code** across 24 test files. Orphaned
+  tests under `core/**/__tests__/*` never ran (vitest config was
+  `include: tests/**/*.test.ts`) and 14 of 18 were broken on
+  import when run directly. Also deleted 5 `describe.skip`'d test
+  suites under `tests/` with abandoned TODOs pointing at APIs
+  that were refactored away (Eden Treaty, ProjectCreator). Plus
+  `vitest.config.live.ts`, an orphan config pointing at a
+  directory that doesn't exist anymore.
+- **`core/plugins/{manager,registry,executor,discovery,dependency-manager,module-resolver,config}.ts`**
+  deleted from FluxStack app. Implementation lives in
+  `@fluxstack/plugin-kit` now. `core/plugins/types.ts` and
+  `core/plugins/index.ts` kept as thin shim barrels that re-export
+  from the lib and specialize `<TConfig>` against `FluxStackConfig`.
+- **Deprecated `configSchema` and `defaultConfig` fields** from the
+  Plugin interface. Were marked `@deprecated` and had no call sites.
+  Plugins use `@fluxstack/config` for declarative config instead.
+- **`loggerPlugin`** — old built-in plugin that was already absent
+  from the real codebase but still referenced in generated templates.
+  Template references removed.
+
+### Validation
+
+- Typecheck (`bunx tsc --noEmit -p tsconfig.api-strict.json`) holds
+  at the 60 pre-existing errors baseline throughout every step —
+  zero regression across all four phases of the extraction.
+- Full test suite: 42 test files, 652 passing, 5 skipped (all
+  intentional individual `it.skip` TODOs).
+- Dev and prod both show `Plugins (4): swagger, live-components,
+  csrf-protection, vite` in the startup banner — identical output.
+
 ## [1.16.0] - 2026-03-13
 
 ### Major Refactor: Extract Live Components to Monorepo

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?