create-fluxstack 1.18.0 → 1.19.0

package/core/plugins/types.ts

@@ -1,463 +1,78 @@
-import type { FluxStackConfig } from "@config"
-import type { Logger } from "@core/utils/logger/index"
-
-export type PluginHook =
-  // Lifecycle hooks
-  | 'setup'
-  | 'onConfigLoad'
-  | 'onBeforeServerStart'
-  | 'onServerStart'
-  | 'onAfterServerStart'
-  | 'onBeforeServerStop'
-  | 'onServerStop'
-  // Request/Response pipeline hooks
-  | 'onRequest'
-  | 'onBeforeRoute'
-  | 'onAfterRoute'
-  | 'onBeforeResponse'
-  | 'onResponse'
-  | 'onRequestValidation'
-  | 'onResponseTransform'
-  // Error handling hooks
-  | 'onError'
-  // Build pipeline hooks
-  | 'onBeforeBuild'
-  | 'onBuild'
-  | 'onBuildAsset'
-  | 'onBuildComplete'
-  | 'onBuildError'
-  // Plugin system hooks
-  | 'onPluginRegister'
-  | 'onPluginUnregister'
-  | 'onPluginError'
-
-export type PluginPriority = 'highest' | 'high' | 'normal' | 'low' | 'lowest' | number
-
-export interface PluginClientHooksAPI {
-  /**
-   * Register JavaScript code to be executed on the client at a specific hook point.
-   *
-   * Built-in hook points:
-   * - 'onEdenInit'    — runs after the Eden Treaty client is created
-   * - 'onLiveConnect'  — runs when the LiveComponents WebSocket connects
-   *
-   * @param hookName - The hook point name
-   * @param jsCode - JavaScript code string to execute on the client
-   */
-  register(hookName: string, jsCode: string): void
-}
-
-export interface PluginContext {
-  config: FluxStackConfig
-  logger: Logger
-  app: unknown // Elysia app
-  utils: PluginUtils
-  registry?: unknown // Plugin registry reference
-  /** Register client-side JS hooks that plugins can inject */
-  clientHooks: PluginClientHooksAPI
-}
-
-export interface PluginUtils {
-  // Utility functions that plugins can use
-  createTimer: (label: string) => { end: () => number }
-  formatBytes: (bytes: number) => string
-  isProduction: () => boolean
-  isDevelopment: () => boolean
-  getEnvironment: () => string
-  createHash: (data: string) => string
-  deepMerge: (target: Record<string, unknown>, source: Record<string, unknown>) => Record<string, unknown>
-  validateSchema: (data: Record<string, unknown>, schema: PluginConfigSchema) => { valid: boolean; errors: string[] }
-}
-
-export interface RequestContext {
-  request: Request
-  path: string
-  method: string
-  headers: Record<string, string>
-  query: Record<string, string>
-  params: Record<string, string>
-  body?: unknown
-  user?: unknown
-  startTime: number
-  handled?: boolean
-  response?: Response
-}
-
-export interface ResponseContext extends RequestContext {
-  response: Response
-  statusCode: number
-  duration: number
-  size?: number
-}
-
-export interface ErrorContext extends RequestContext {
-  error: Error
-  duration: number
-  handled: boolean
-}
-
-export interface BuildContext {
-  target: string
-  outDir: string
-  mode: 'development' | 'production'
-  config: FluxStackConfig
-}
-
-export interface ConfigLoadContext {
-  config: FluxStackConfig
-  envVars: Record<string, string | undefined>
-  configPath?: string
-}
-
-export interface RouteContext extends RequestContext {
-  route?: string
-  handler?: Function
-  params: Record<string, string>
-}
-
-export interface ValidationContext extends RequestContext {
-  errors: Array<{ field: string; message: string; code: string }>
-  isValid: boolean
-}
-
-export interface TransformContext extends ResponseContext {
-  transformed: boolean
-  originalResponse?: Response
-}
-
-export interface BuildAssetContext {
-  assetPath: string
-  assetType: 'js' | 'css' | 'html' | 'image' | 'font' | 'other'
-  size: number
-  content?: string | Buffer
-}
-
-export interface BuildErrorContext {
-  error: Error
-  file?: string
-  line?: number
-  column?: number
-}
-
-export interface PluginEventContext {
-  pluginName: string
-  pluginVersion?: string
-  timestamp: number
-  data?: unknown
-}
-
-export interface PluginConfigSchema {
-  type: 'object'
-  properties: Record<string, unknown>
-  required?: string[]
-  additionalProperties?: boolean
-}
-
+/**
+ * FluxStack plugin types — thin re-export layer over @fluxstack/plugin-kit.
+ *
+ * Historically this file was the canonical source. As of the plugin-kit
+ * extraction (see .ai-notes/plans/2026-04-11-plugin-kit-extraction.md),
+ * the canonical source is `@fluxstack/plugin-kit`. This file exists to:
+ *
+ * 1. Preserve every existing `import ... from '@core/plugins/types'` call
+ *    site in the FluxStack app — no downstream code needs to change.
+ * 2. Specialize the generic `<TConfig>` parameters against FluxStack's
+ *    concrete `FluxStackConfig`, so consumers get full autocomplete
+ *    against the app's real config shape.
+ *
+ * Future PRs will migrate individual call sites to import directly from
+ * `@fluxstack/plugin-kit` and this shim will eventually be deleted.
+ */
+
+import type { FluxStackConfig } from '@config'
+import type {
+  Plugin as BasePlugin,
+  PluginContext as BasePluginContext,
+  BuildContext as BaseBuildContext,
+  ConfigLoadContext as BaseConfigLoadContext,
+  CliCommand as BaseCliCommand,
+  CliContext as BaseCliContext,
+  PluginLoadResult as BasePluginLoadResult,
+  PluginRegistryState as BasePluginRegistryState,
+  PluginExecutionContext as BasePluginExecutionContext,
+} from '@fluxstack/plugin-kit'
+
+// ─── Specialized generics (FluxStack passes FluxStackConfig everywhere) ───
+
+export type Plugin = BasePlugin<FluxStackConfig>
+export type PluginContext = BasePluginContext<FluxStackConfig>
+export type BuildContext = BaseBuildContext<FluxStackConfig>
+export type ConfigLoadContext = BaseConfigLoadContext<FluxStackConfig>
+export type CliCommand = BaseCliCommand<FluxStackConfig>
+export type CliContext = BaseCliContext<FluxStackConfig>
+export type PluginLoadResult = BasePluginLoadResult<FluxStackConfig>
+export type PluginRegistryState = BasePluginRegistryState<FluxStackConfig>
+export type PluginExecutionContext = BasePluginExecutionContext<FluxStackConfig>
+
+// ─── Straight re-exports (no generic to specialize) ───
+
+export type {
+  Logger,
+  PluginHook,
+  PluginPriority,
+  PluginLifecycleEvent,
+  HookExecutionOptions,
+  PluginClientHooksAPI,
+  PluginUtils,
+  PluginConfigSchema,
+  RequestContext,
+  ResponseContext,
+  ErrorContext,
+  RouteContext,
+  ValidationContext,
+  TransformContext,
+  BuildAssetContext,
+  BuildErrorContext,
+  PluginEventContext,
+  CliArgument,
+  CliOption,
+  PluginManifest,
+  PluginHookResult,
+  PluginMetrics,
+  PluginDiscoveryOptions,
+  PluginInstallOptions,
+  PluginValidationResult,
+} from '@fluxstack/plugin-kit'
+
+// ─── Namespace backward-compat ───
+// Legacy code uses `FluxStack.Plugin` — keep that form working.
+// eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace FluxStack {
-  export interface Plugin {
-  name: string
-  version?: string
-  description?: string
-  author?: string
-  dependencies?: string[]
-  priority?: number | PluginPriority
-  category?: string
-  tags?: string[]
-
-  // Lifecycle hooks
-  setup?: (context: PluginContext) => void | Promise<void>
-  onConfigLoad?: (context: ConfigLoadContext) => void | Promise<void>
-  onBeforeServerStart?: (context: PluginContext) => void | Promise<void>
-  onServerStart?: (context: PluginContext) => void | Promise<void>
-  onAfterServerStart?: (context: PluginContext) => void | Promise<void>
-  onBeforeServerStop?: (context: PluginContext) => void | Promise<void>
-  onServerStop?: (context: PluginContext) => void | Promise<void>
-
-  // Request/Response pipeline hooks
-  onRequest?: (context: RequestContext) => void | Promise<void>
-  onBeforeRoute?: (context: RequestContext) => void | Promise<void>
-  onAfterRoute?: (context: RouteContext) => void | Promise<void>
-  onBeforeResponse?: (context: ResponseContext) => void | Promise<void>
-  onResponse?: (context: ResponseContext) => void | Promise<void>
-  onRequestValidation?: (context: ValidationContext) => void | Promise<void>
-  onResponseTransform?: (context: TransformContext) => void | Promise<void>
-
-  // Error handling hooks
-  onError?: (context: ErrorContext) => void | Promise<void>
-
-  // Build pipeline hooks
-  onBeforeBuild?: (context: BuildContext) => void | Promise<void>
-  onBuild?: (context: BuildContext) => void | Promise<void>
-  onBuildAsset?: (context: BuildAssetContext) => void | Promise<void>
-  onBuildComplete?: (context: BuildContext) => void | Promise<void>
-  onBuildError?: (context: BuildErrorContext) => void | Promise<void>
-
-  // Plugin system hooks
-  onPluginRegister?: (context: PluginEventContext) => void | Promise<void>
-  onPluginUnregister?: (context: PluginEventContext) => void | Promise<void>
-  onPluginError?: (context: PluginEventContext & { error: Error }) => void | Promise<void>
-
-  // Configuration
-  /**
-   * @deprecated Use declarative config system instead (plugins/[name]/config/)
-   * Create a config/ folder with defineConfig() for type-safe configuration.
-   * This property is kept for backward compatibility with built-in plugins.
-   *
-   * @example
-   * // ✅ New way (recommended):
-   * // plugins/my-plugin/config/index.ts
-   * import { defineConfig, config } from '@fluxstack/config'
-   * export const myConfig = defineConfig({ ... })
-   *
-   * // ❌ Old way (deprecated):
-   * configSchema: { type: 'object', properties: { ... } }
-   */
-  configSchema?: PluginConfigSchema
-
-  /**
-   * @deprecated Use declarative config system with defineConfig()
-   * This property will be removed in a future major version.
-   * Use the config/ folder structure for automatic type inference.
-   */
-  defaultConfig?: unknown
-
-  // CLI commands
-  commands?: CliCommand[]
-  }
-}
-
-
-export interface PluginManifest {
-  name: string
-  version: string
-  description: string
-  author: string
-  license: string
-  homepage?: string
-  repository?: string
-  keywords: string[]
-  dependencies: Record<string, string>
-  peerDependencies?: Record<string, string>
-  fluxstack: {
-    version: string
-    hooks: PluginHook[]
-    config?: PluginConfigSchema
-    category?: string
-    tags?: string[]
-  }
-}
-
-export interface PluginLoadResult {
-  success: boolean
-  plugin?: FluxStack.Plugin
-  error?: string
-  warnings?: string[]
-}
-
-export interface PluginRegistryState {
-  plugins: Map<string, FluxStack.Plugin>
-  manifests: Map<string, PluginManifest>
-  loadOrder: string[]
-  dependencies: Map<string, string[]>
-  conflicts: string[]
-}
-
-export interface PluginHookResult {
-  success: boolean
-  error?: Error
-  duration: number
-  plugin: string
-  hook: PluginHook
-  context?: unknown
-}
-
-export interface PluginMetrics {
-  loadTime: number
-  setupTime: number
-  hookExecutions: Map<PluginHook, number>
-  errors: number
-  warnings: number
-  lastExecution?: Date
-}
-
-export interface PluginDiscoveryOptions {
-  directories?: string[]
-  patterns?: string[]
-  includeBuiltIn?: boolean
-  includeExternal?: boolean
-  includeNpm?: boolean
-}
-
-export interface PluginInstallOptions {
-  version?: string
-  registry?: string
-  force?: boolean
-  dev?: boolean
-  source?: 'npm' | 'git' | 'local'
-}
-
-export interface PluginExecutionContext {
-  plugin: FluxStack.Plugin
-  hook: PluginHook
-  startTime: number
-  timeout?: number
-  retries?: number
-}
-
-export interface PluginValidationResult {
-  valid: boolean
-  errors: string[]
-  warnings: string[]
-}
-
-// Plugin hook execution options
-export interface HookExecutionOptions {
-  timeout?: number
-  parallel?: boolean
-  stopOnError?: boolean
-  retries?: number
-}
-
-// Plugin lifecycle events
-export type PluginLifecycleEvent = 
-  | 'plugin:registered'
-  | 'plugin:unregistered'
-  | 'plugin:enabled'
-  | 'plugin:disabled'
-  | 'plugin:error'
-  | 'hook:before'
-  | 'hook:after'
-  | 'hook:error'
-
-// CLI Command interfaces
-export interface CliArgument {
-  name: string
-  description: string
-  required?: boolean
-  type?: 'string' | 'number' | 'boolean'
-  default?: unknown
-  choices?: string[]
+  export type Plugin = BasePlugin<FluxStackConfig>
 }
-
-export interface CliOption {
-  name: string
-  short?: string
-  description: string
-  type?: 'string' | 'number' | 'boolean' | 'array'
-  default?: unknown
-  required?: boolean
-  choices?: string[]
-}
-
-export interface CliCommand {
-  name: string
-  description: string
-  usage?: string
-  examples?: string[]
-  arguments?: CliArgument[]
-  options?: CliOption[]
-  aliases?: string[]
-  category?: string
-  hidden?: boolean
-  handler: (args: unknown[], options: Record<string, unknown>, context: CliContext) => Promise<void> | void
-}
-
-export interface CliContext {
-  config: FluxStackConfig
-  logger: Logger
-  utils: PluginUtils
-  workingDir: string
-  packageInfo: {
-    name: string
-    version: string
-  }
-}
-
-// Live Components Types - Re-exported from core/types/types.ts
-// See core/types/types.ts for full implementation
-// Note: These are re-exported at the end of this file
-
-// File Upload Types
-export interface ActiveUpload {
-  uploadId: string
-  componentId?: string
-  filename: string
-  fileType?: string
-  fileSize?: number
-  totalChunks: number
-  receivedChunks: Map<number, unknown>
-  startTime: number
-  lastChunkTime?: number
-}
-
-export interface FileUploadStartMessage {
-  type: 'upload:start' | 'FILE_UPLOAD_START'
-  uploadId: string
-  filename: string
-  totalChunks: number
-  fileSize: number
-  componentId?: string
-  fileType?: string
-  chunkSize?: number
-  requestId?: string
-}
-
-export interface FileUploadChunkMessage {
-  type: 'upload:chunk' | 'FILE_UPLOAD_CHUNK'
-  uploadId: string
-  chunkIndex: number
-  data: string | ArrayBuffer
-  totalChunks?: number
-  componentId?: string
-  requestId?: string
-}
-
-export interface FileUploadCompleteMessage {
-  type: 'upload:complete' | 'FILE_UPLOAD_COMPLETE'
-  uploadId: string
-  requestId?: string
-}
-
-export interface FileUploadProgressResponse {
-  type: 'upload:progress' | 'FILE_UPLOAD_PROGRESS'
-  uploadId: string
-  receivedChunks?: number
-  totalChunks?: number
-  percentage?: number
-  componentId?: string
-  chunkIndex?: number
-  bytesUploaded?: number
-  totalBytes?: number
-  progress?: number
-  timestamp?: number
-}
-
-export interface FileUploadCompleteResponse {
-  type: 'upload:complete' | 'FILE_UPLOAD_COMPLETE'
-  uploadId: string
-  url?: string
-  filename?: string
-  size?: number
-  componentId?: string
-  success?: boolean
-  error?: string
-  message?: string
-  fileUrl?: string
-  timestamp?: number
-}
-
-// Plugin Type Export
-export type Plugin = FluxStack.Plugin
-
-// Re-export all WebSocket and LiveComponent types from core/types/types.ts
-export {
-  LiveComponent,
-  type FluxStackWebSocket,
-  type FluxStackWSData,
-  type FluxStackServerWebSocket,
-  type LiveMessage,
-  type BroadcastMessage,
-  type ComponentState,
-  type ComponentDefinition,
-  type WebSocketData
-} from '@core/types/types'

package/core/server/index.ts

@@ -2,7 +2,7 @@
 export { FluxStackFramework } from "../framework/server"
 export { vitePlugin } from "../plugins/built-in"
 export { swaggerPlugin } from "../plugins/built-in/swagger"
-export { PluginRegistry } from "../plugins/registry"
+export { PluginRegistry } from "@fluxstack/plugin-kit"
 export * from "../types"
 
 // Live Components exports

package/core/utils/logger/startup-banner.ts

@@ -22,6 +22,17 @@ export interface StartupInfo {
   viteEmbedded?: boolean // true when Vite runs programmatically with backend
   swaggerPath?: string
   liveComponents?: string[]
+  /**
+   * List of registered plugins to display. If omitted, falls back to
+   * the legacy `globalThis.__fluxstackPlugins` convention for backwards
+   * compatibility with plugins that still push themselves there.
+   *
+   * Prefer passing this explicitly — read it from the PluginRegistry
+   * (`framework.getPluginRegistry().getAll()`) so the banner reflects
+   * exactly what's in the registry, not what each plugin manually
+   * decided to advertise.
+   */
+  plugins?: Array<{ name: string }>
 }
 
 /**
@@ -43,8 +54,14 @@ export function displayStartupBanner(info: StartupInfo): void {
   const displayHost = host === '0.0.0.0' ? 'localhost' : host
   const serverUrl = `http://${displayHost}:${port}`
 
-  // Simple ready message with URL
-  console.log(chalk.green('\nServer ready!') + chalk.gray(` Environment: ${environment}${viteEmbedded ? ' | Vite: embedded' : ''}`))
+  // Simple ready message with URL.
+  // "Vite: embedded" only makes sense in development, where the vite
+  // plugin actually runs the Vite dev server. In production, the same
+  // plugin acts as a static-file fallback (serving the compiled
+  // dist/client bundle), so the "Vite: embedded" label is misleading.
+  const isDev = environment === 'development'
+  const viteLabel = viteEmbedded && isDev ? ' | Vite: embedded' : ''
+  console.log(chalk.green('\nServer ready!') + chalk.gray(` Environment: ${environment}${viteLabel}`))
   console.log(chalk.cyan(`  → ${serverUrl}`))
 
   // Display Live Components
@@ -52,8 +69,13 @@ export function displayStartupBanner(info: StartupInfo): void {
     console.log(chalk.gray(`  Live Components (${liveComponents.length}): `) + chalk.yellow(liveComponents.join(', ')))
   }
 
-  // Display plugins in compact format
-  const plugins = ((globalThis as Record<string, unknown>).__fluxstackPlugins || []) as Array<{ name: string }>
+  // Display plugins in compact format. Prefer the explicit list from
+  // info.plugins (read from the PluginRegistry); fall back to the
+  // legacy global convention if the caller didn't pass anything.
+  const plugins =
+    info.plugins ??
+    (((globalThis as Record<string, unknown>).__fluxstackPlugins ||
+      []) as Array<{ name: string }>)
   if (plugins.length > 0) {
     const pluginList = plugins.map((p) => p.name).join(', ')
     console.log(chalk.gray(`  Plugins (${plugins.length}): `) + chalk.magenta(pluginList))

package/core/utils/version.ts

@@ -1,6 +1,6 @@
-/**
- * FluxStack Framework Version
- * Single source of truth for version number
- * Auto-synced with package.json
- */
-export const FLUXSTACK_VERSION = '1.18.0'
+/**
+ * FluxStack Framework Version
+ * Single source of truth for version number
+ * Auto-synced with package.json
+ */
+export const FLUXSTACK_VERSION = '1.19.0'