@spfn/core 0.1.0-alpha.83 → 0.1.0-alpha.85

package/dist/server/index.d.ts

@@ -6,6 +6,57 @@ import { serve } from '@hono/node-server';
  * CORS configuration options - inferred from hono/cors
  */
 type CorsConfig = Parameters<typeof cors>[0];
+/**
+ * SPFN Plugin Interface
+ *
+ * Allows packages to automatically hook into server lifecycle
+ * Plugins are auto-discovered from @spfn/* packages in node_modules
+ *
+ * @example
+ * ```typescript
+ * // packages/auth/src/plugin.ts
+ * export const spfnPlugin: ServerPlugin = {
+ *   name: '@spfn/auth',
+ *   afterInfrastructure: async () => {
+ *     await initializeAuth();
+ *   },
+ *   beforeRoutes: async (app) => {
+ *     app.route('/_auth', authRoutes);
+ *   }
+ * };
+ * ```
+ */
+interface ServerPlugin {
+    /**
+     * Plugin name (should match package name)
+     */
+    name: string;
+    /**
+     * Hook: Run after infrastructure (DB/Redis) initialization
+     * Use for: migrations, seeding, RBAC setup
+     */
+    afterInfrastructure?: () => Promise<void>;
+    /**
+     * Hook: Run before routes are loaded
+     * Use for: mounting plugin routes, adding middleware
+     */
+    beforeRoutes?: (app: Hono) => Promise<void>;
+    /**
+     * Hook: Run after all routes are loaded
+     * Use for: final setup, fallback handlers
+     */
+    afterRoutes?: (app: Hono) => Promise<void>;
+    /**
+     * Hook: Run after server starts successfully
+     * Use for: notifications, health checks
+     */
+    afterStart?: (instance: ServerInstance) => Promise<void>;
+    /**
+     * Hook: Run before graceful shutdown
+     * Use for: cleanup plugin resources
+     */
+    beforeShutdown?: () => Promise<void>;
+}
 /**
  * Server Configuration Options
  *
@@ -405,7 +456,7 @@ declare module 'hono' {
  * 2. server.config.ts -> Partial customization
  * 3. app.ts -> Full control (no auto config)
  */
-declare function createServer(config?: ServerConfig): Promise<Hono>;
+declare function createServer(config?: ServerConfig, plugins?: ServerPlugin[]): Promise<Hono>;
 
 /**
  * Start SPFN Server
@@ -424,4 +475,4 @@ declare function createServer(config?: ServerConfig): Promise<Hono>;
  */
 declare function startServer(config?: ServerConfig): Promise<ServerInstance>;
 
-export { type AppFactory, type ServerConfig, type ServerInstance, createServer, startServer };
+export { type AppFactory, type ServerConfig, type ServerInstance, type ServerPlugin, createServer, startServer };

package/dist/server/index.js

@@ -3111,29 +3111,133 @@ function buildStartupConfig(config, timeouts) {
   };
 }
 
+// src/server/plugin-discovery.ts
+init_logger2();
+var pluginLogger = logger.child("plugin");
+async function discoverPlugins(cwd = process.cwd()) {
+  const plugins = [];
+  const nodeModulesPath = join(cwd, "node_modules");
+  try {
+    const projectPkgPath = join(cwd, "package.json");
+    if (!existsSync(projectPkgPath)) {
+      pluginLogger.debug("No package.json found, skipping plugin discovery");
+      return plugins;
+    }
+    const projectPkg = JSON.parse(readFileSync(projectPkgPath, "utf-8"));
+    const dependencies = {
+      ...projectPkg.dependencies,
+      ...projectPkg.devDependencies
+    };
+    for (const [packageName] of Object.entries(dependencies)) {
+      if (!packageName.startsWith("@spfn/")) {
+        continue;
+      }
+      try {
+        const plugin = await loadPluginFromPackage(packageName, nodeModulesPath);
+        if (plugin) {
+          plugins.push(plugin);
+          pluginLogger.info("Plugin discovered", {
+            name: plugin.name,
+            hooks: getPluginHookNames(plugin)
+          });
+        }
+      } catch (error) {
+        pluginLogger.debug("Failed to load plugin", {
+          package: packageName,
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+      }
+    }
+  } catch (error) {
+    pluginLogger.warn("Plugin discovery failed", {
+      error: error instanceof Error ? error.message : "Unknown error"
+    });
+  }
+  return plugins;
+}
+async function loadPluginFromPackage(packageName, nodeModulesPath) {
+  const pkgPath = join(nodeModulesPath, ...packageName.split("/"), "package.json");
+  if (!existsSync(pkgPath)) {
+    return null;
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  const packageDir = dirname(pkgPath);
+  const mainEntry = pkg.main || "dist/index.js";
+  const mainPath = join(packageDir, mainEntry);
+  if (!existsSync(mainPath)) {
+    return null;
+  }
+  try {
+    const module = await import(mainPath);
+    if (module.spfnPlugin && isValidPlugin(module.spfnPlugin)) {
+      return module.spfnPlugin;
+    }
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+function isValidPlugin(plugin) {
+  return plugin && typeof plugin === "object" && typeof plugin.name === "string" && (typeof plugin.afterInfrastructure === "function" || typeof plugin.beforeRoutes === "function" || typeof plugin.afterRoutes === "function" || typeof plugin.afterStart === "function" || typeof plugin.beforeShutdown === "function");
+}
+function getPluginHookNames(plugin) {
+  const hooks = [];
+  if (plugin.afterInfrastructure) hooks.push("afterInfrastructure");
+  if (plugin.beforeRoutes) hooks.push("beforeRoutes");
+  if (plugin.afterRoutes) hooks.push("afterRoutes");
+  if (plugin.afterStart) hooks.push("afterStart");
+  if (plugin.beforeShutdown) hooks.push("beforeShutdown");
+  return hooks;
+}
+async function executePluginHooks(plugins, hookName, ...args) {
+  for (const plugin of plugins) {
+    const hook = plugin[hookName];
+    if (typeof hook === "function") {
+      try {
+        pluginLogger.debug("Executing plugin hook", {
+          plugin: plugin.name,
+          hook: hookName
+        });
+        await hook(...args);
+      } catch (error) {
+        pluginLogger.error("Plugin hook failed", {
+          plugin: plugin.name,
+          hook: hookName,
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+        throw new Error(
+          `Plugin ${plugin.name} failed in ${hookName} hook: ${error instanceof Error ? error.message : "Unknown error"}`
+        );
+      }
+    }
+  }
+}
+
 // src/server/create-server.ts
 var serverLogger = logger.child("server");
-async function createServer(config) {
+async function createServer(config, plugins = []) {
   const cwd = process.cwd();
   const appPath = join(cwd, "src", "server", "app.ts");
   const appJsPath = join(cwd, "src", "server", "app.js");
   if (existsSync(appPath) || existsSync(appJsPath)) {
-    return await loadCustomApp(appPath, appJsPath, config);
+    return await loadCustomApp(appPath, appJsPath, config, plugins);
   }
-  return await createAutoConfiguredApp(config);
+  return await createAutoConfiguredApp(config, plugins);
 }
-async function loadCustomApp(appPath, appJsPath, config) {
+async function loadCustomApp(appPath, appJsPath, config, plugins = []) {
   const appModule = await (existsSync(appPath) ? import(appPath) : import(appJsPath));
   const appFactory = appModule.default;
   if (!appFactory) {
     throw new Error("app.ts must export a default function that returns a Hono app");
   }
   const app = await appFactory();
+  await executePluginHooks(plugins, "beforeRoutes", app);
   const debug = config?.debug ?? process.env.NODE_ENV === "development";
   await loadRoutes(app, { routesDir: config?.routesPath, debug });
+  await executePluginHooks(plugins, "afterRoutes", app);
   return app;
 }
-async function createAutoConfiguredApp(config) {
+async function createAutoConfiguredApp(config, plugins = []) {
   const app = new Hono();
   const middlewareConfig = config?.middleware ?? {};
   const enableLogger = middlewareConfig.logger !== false;
@@ -3149,8 +3253,10 @@ async function createAutoConfiguredApp(config) {
   config?.use?.forEach((mw) => app.use("*", mw));
   registerHealthCheckEndpoint(app, config);
   await executeBeforeRoutesHook(app, config);
+  await executePluginHooks(plugins, "beforeRoutes", app);
   await loadAppRoutes(app, config);
   await executeAfterRoutesHook(app, config);
+  await executePluginHooks(plugins, "afterRoutes", app);
   if (enableErrorHandler) {
     app.onError(ErrorHandler());
   }
@@ -3295,9 +3401,17 @@ async function startServer(config) {
   if (debug) {
     logMiddlewareOrder(finalConfig);
   }
+  serverLogger2.debug("Discovering plugins...");
+  const plugins = await discoverPlugins();
+  if (plugins.length > 0) {
+    serverLogger2.info("Plugins discovered", {
+      count: plugins.length,
+      plugins: plugins.map((p) => p.name)
+    });
+  }
   try {
-    await initializeInfrastructure(finalConfig);
-    const app = await createServer(finalConfig);
+    await initializeInfrastructure(finalConfig, plugins);
+    const app = await createServer(finalConfig, plugins);
     const server = startHttpServer(app, host, port);
     const timeouts = getTimeoutConfig(finalConfig.timeout);
     applyServerTimeouts(server, timeouts);
@@ -3308,7 +3422,7 @@ async function startServer(config) {
       port
     });
     logServerStarted(debug, host, port, finalConfig, timeouts);
-    const shutdownServer = createShutdownHandler(server, finalConfig);
+    const shutdownServer = createShutdownHandler(server, finalConfig, plugins);
     const shutdown = createGracefulShutdown(shutdownServer, finalConfig);
     registerShutdownHandlers(shutdown);
     const serverInstance = {
@@ -3328,6 +3442,7 @@ async function startServer(config) {
         serverLogger2.error("afterStart hook failed", error);
       }
     }
+    await executePluginHooks(plugins, "afterStart", serverInstance);
     return serverInstance;
   } catch (error) {
     const err = error;
@@ -3369,7 +3484,7 @@ function logMiddlewareOrder(config) {
     order: middlewareOrder
   });
 }
-async function initializeInfrastructure(config) {
+async function initializeInfrastructure(config, plugins) {
   if (config.lifecycle?.beforeInfrastructure) {
     serverLogger2.debug("Executing beforeInfrastructure hook...");
     try {
@@ -3402,14 +3517,16 @@ async function initializeInfrastructure(config) {
       throw new Error("Server initialization failed in afterInfrastructure hook");
     }
   }
+  await executePluginHooks(plugins, "afterInfrastructure");
 }
 function startHttpServer(app, host, port) {
   serverLogger2.debug(`Starting server on ${host}:${port}...`);
-  return serve({
+  const server = serve({
     fetch: app.fetch,
     port,
     hostname: host
   });
+  return server;
 }
 function logServerTimeouts(timeouts) {
   serverLogger2.info("Server timeouts configured", {
@@ -3427,7 +3544,7 @@ function logServerStarted(debug, host, port, config, timeouts) {
     config: startupConfig
   });
 }
-function createShutdownHandler(server, config) {
+function createShutdownHandler(server, config, plugins) {
   return async () => {
     serverLogger2.debug("Closing HTTP server...");
     await new Promise((resolve) => {
@@ -3444,6 +3561,11 @@ function createShutdownHandler(server, config) {
         serverLogger2.error("beforeShutdown hook failed", error);
       }
     }
+    try {
+      await executePluginHooks(plugins, "beforeShutdown");
+    } catch (error) {
+      serverLogger2.error("Plugin beforeShutdown hooks failed", error);
+    }
     const shouldCloseDatabase = config.infrastructure?.database !== false;
     const shouldCloseRedis = config.infrastructure?.redis !== false;
     if (shouldCloseDatabase) {
@@ -3489,15 +3611,28 @@ function registerShutdownHandlers(shutdown) {
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("uncaughtException", (error) => {
-    serverLogger2.error("Uncaught exception", error);
-    shutdown("UNCAUGHT_EXCEPTION");
+    if (error.message?.includes("EADDRINUSE")) {
+      serverLogger2.error("Port conflict detected - detailed trace:", {
+        error: error.message,
+        stack: error.stack,
+        code: error.code,
+        port: error.port,
+        address: error.address,
+        syscall: error.syscall
+      });
+    } else {
+      serverLogger2.error("Uncaught exception", error);
+    }
+    serverLogger2.info("Exiting immediately for clean restart");
+    process.exit(1);
   });
   process.on("unhandledRejection", (reason, promise) => {
     serverLogger2.error("Unhandled promise rejection", {
       reason,
       promise
     });
-    shutdown("UNHANDLED_REJECTION");
+    serverLogger2.info("Exiting immediately for clean restart");
+    process.exit(1);
   });
 }
 async function cleanupOnFailure(config) {