@kuckit/app-server 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { CoreConfig, CoreCradle, ModuleSpec } from "@kuckit/sdk";
+import express, { Express, NextFunction, Request, Response } from "express";
+import { AwilixContainer } from "awilix";
+import { Pool } from "pg";
+import { Logger, UserRepository } from "@kuckit/domain";
+import { StructuredLogger } from "@kuckit/infrastructure";
+
+//#region src/types.d.ts
+
+/**
+ * Extended configuration for Kuckit server applications
+ * Extends CoreConfig with server-specific settings
+ */
+interface KuckitServerConfig extends CoreConfig {
+  port: number;
+  corsOrigin: string;
+}
+/**
+ * Extended cradle for Kuckit server applications
+ * Includes core services plus commonly-used server dependencies
+ */
+interface KuckitServerCradle extends CoreCradle {
+  config: KuckitServerConfig;
+  dbPool: Pool;
+  logger: Logger & StructuredLogger;
+  userRepository: UserRepository;
+}
+type KuckitContainer = AwilixContainer<KuckitServerCradle>;
+/**
+ * Options for configuring the Kuckit server
+ */
+interface KuckitServerOptions {
+  /**
+   * Load server configuration from environment variables.
+   * Must return a config object extending KuckitServerConfig.
+   */
+  loadConfig: () => KuckitServerConfig;
+  /**
+   * Get module specifications for the application.
+   * Can be async for dynamic module loading.
+   */
+  getModuleSpecs: () => ModuleSpec[] | Promise<ModuleSpec[]>;
+  /**
+   * Optional hooks for customizing server behavior
+   */
+  hooks?: KuckitServerHooks;
+}
+/**
+ * Hooks for customizing server behavior at various lifecycle points
+ */
+interface KuckitServerHooks {
+  /**
+   * Called after the Express app is created, before any middleware is added.
+   * Use this to add custom middleware that should run first.
+   */
+  onAppCreated?: (app: Express) => void | Promise<void>;
+  /**
+   * Called after the DI container is built and modules are loaded.
+   * Use this to register additional dependencies or perform post-load setup.
+   */
+  onContainerReady?: (container: KuckitContainer) => void | Promise<void>;
+  /**
+   * Called after all routes are set up, before the server starts listening.
+   * Use this to add custom routes or final middleware.
+   */
+  onRoutesReady?: (app: Express, container: KuckitContainer) => void | Promise<void>;
+  /**
+   * Called after the server starts listening.
+   * Use this for post-startup tasks like logging or health checks.
+   */
+  onServerReady?: (port: number, container: KuckitContainer) => void | Promise<void>;
+  /**
+   * Called during graceful shutdown.
+   * Use this to clean up custom resources before the container is disposed.
+   */
+  onShutdown?: (container: KuckitContainer) => void | Promise<void>;
+}
+/**
+ * Result of creating a Kuckit server without starting it
+ */
+interface KuckitServer {
+  app: Express;
+  container: KuckitContainer;
+  start: () => Promise<{
+    port: number;
+    close: () => Promise<void>;
+  }>;
+}
+/**
+ * Context for oRPC procedures
+ */
+interface KuckitContext {
+  di: KuckitContainer;
+  session: unknown;
+  requestId: string;
+}
+/**
+ * Extended Express Request with DI scope
+ */
+interface KuckitRequest extends Request {
+  scope: AwilixContainer<KuckitServerCradle>;
+}
+/**
+ * Middleware function type for Kuckit
+ */
+type KuckitMiddleware = (req: KuckitRequest, res: Response, next: NextFunction) => void | Promise<void>;
+//#endregion
+//#region src/express/server.d.ts
+/**
+ * Cleanup container resources
+ */
+declare const disposeContainer: (container: KuckitContainer) => Promise<void>;
+/**
+ * Create a Kuckit server without starting it.
+ * Useful for testing or when you need access to the app/container before listening.
+ */
+declare const createKuckitServer: (options: KuckitServerOptions) => Promise<KuckitServer>;
+/**
+ * Run a Kuckit server - the main entry point for server applications.
+ * Creates the server and immediately starts listening.
+ */
+declare const runKuckitServer: (options: KuckitServerOptions) => Promise<{
+  port: number;
+  close: () => Promise<void>;
+}>;
+/**
+ * Create a headless Kuckit context (DI container only, no Express app).
+ * Useful for CLI tools, scripts, testing, or background workers.
+ */
+declare const createKuckitContext: (options: KuckitServerOptions) => Promise<{
+  container: KuckitContainer;
+  dispose: () => Promise<void>;
+}>;
+//#endregion
+//#region src/express/app.d.ts
+interface CreateAppOptions {
+  config: KuckitServerConfig;
+}
+/**
+ * Create and configure Express app with CORS
+ */
+declare const createKuckitApp: (options: CreateAppOptions) => Express;
+//#endregion
+//#region src/express/middleware.d.ts
+/**
+ * Setup container middleware that creates per-request DI scopes
+ */
+declare const setupContainerMiddleware: (app: Express, rootContainer: KuckitContainer) => void;
+//#endregion
+//#region src/express/routes.d.ts
+type AnyRouter = any;
+/**
+ * Options for setting up routes
+ */
+interface SetupRoutesOptions {
+  /**
+   * The RPC router object. Module routers should already be wired into this.
+   */
+  rpcRouter: AnyRouter;
+  /**
+   * REST router entries from modules (for streaming endpoints)
+   */
+  restRouters?: Array<{
+    name: string;
+    router: express.Router;
+    basePath: string;
+  }>;
+}
+/**
+ * Setup Better-Auth routes
+ */
+declare const setupAuth: (app: Express) => void;
+/**
+ * Setup oRPC handler
+ */
+declare const setupRPC: (app: Express, options: SetupRoutesOptions) => void;
+/**
+ * Setup OpenAPI documentation
+ */
+declare const setupAPIReference: (app: Express, options: SetupRoutesOptions) => void;
+/**
+ * Setup REST routers from modules
+ */
+declare const setupModuleRestRouters: (app: Express, options: SetupRoutesOptions) => void;
+/**
+ * Setup health check endpoint
+ */
+declare const setupHealth: (app: Express, container: KuckitContainer) => void;
+/**
+ * Setup Prometheus metrics endpoint
+ */
+declare const setupMetrics: (app: Express, container: KuckitContainer) => void;
+/**
+ * Setup static file serving (production only)
+ */
+declare const setupStaticFiles: (app: Express, publicDir?: string) => void;
+/**
+ * Setup error handling middleware (must be last)
+ */
+declare const setupErrorMiddleware: (app: Express) => void;
+//#endregion
+export { type CreateAppOptions, type KuckitContainer, type KuckitContext, type KuckitMiddleware, type KuckitRequest, type KuckitServer, type KuckitServerConfig, type KuckitServerCradle, type KuckitServerHooks, type KuckitServerOptions, type SetupRoutesOptions, createKuckitApp, createKuckitContext, createKuckitServer, disposeContainer, runKuckitServer, setupAPIReference, setupAuth, setupContainerMiddleware, setupErrorMiddleware, setupHealth, setupMetrics, setupModuleRestRouters, setupRPC, setupStaticFiles };

package/dist/index.js

@@ -0,0 +1,341 @@
+import { createKuckitContainer, loadKuckitModules } from "@kuckit/sdk";
+import { appRouter } from "@kuckit/api/routers/index";
+import express from "express";
+import cors from "cors";
+import { asValue } from "awilix";
+import path from "path";
+import { RPCHandler } from "@orpc/server/node";
+import { OpenAPIHandler } from "@orpc/openapi/node";
+import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { onError } from "@orpc/server";
+import { fromNodeHeaders, toNodeHandler } from "better-auth/node";
+import { createContext } from "@kuckit/api/context";
+
+//#region src/express/app.ts
+/**
+* Create and configure Express app with CORS
+*/
+const createKuckitApp = (options) => {
+	const { config } = options;
+	const app = express();
+	app.use(cors({
+		origin: config.corsOrigin || "",
+		methods: [
+			"GET",
+			"POST",
+			"OPTIONS"
+		],
+		allowedHeaders: ["Content-Type", "Authorization"],
+		credentials: true
+	}));
+	return app;
+};
+
+//#endregion
+//#region src/express/middleware.ts
+/**
+* Setup container middleware that creates per-request DI scopes
+*/
+const setupContainerMiddleware = (app, rootContainer) => {
+	app.use((req, res, next) => {
+		req.scope = rootContainer.createScope();
+		req.scope.register({ requestId: asValue(crypto.randomUUID()) });
+		res.on("finish", () => {
+			req.scope?.dispose();
+		});
+		res.on("close", () => {
+			req.scope?.dispose();
+		});
+		next();
+	});
+};
+
+//#endregion
+//#region src/express/routes.ts
+/**
+* Middleware to add session to request scope for REST routes.
+*/
+const createSessionMiddleware = () => {
+	return async (req, _res, next) => {
+		if (!req.scope) return next(/* @__PURE__ */ new Error("Request scope not initialized"));
+		const auth = req.scope.cradle.auth;
+		try {
+			if (!auth) throw new Error("Auth not available in request scope");
+			const session = await auth.api.getSession({ headers: fromNodeHeaders(req.headers) });
+			req.scope.register({ session: asValue(session) });
+			next();
+		} catch (error) {
+			console.error("[REST Auth] Failed to get session:", error);
+			req.scope.register({ session: asValue(null) });
+			next();
+		}
+	};
+};
+/**
+* Setup Better-Auth routes
+*/
+const setupAuth = (app) => {
+	app.all("/api/auth{/*path}", (req, res, _next) => {
+		const auth = req.scope?.cradle.auth;
+		if (!auth) return res.status(500).json({ error: "Auth not initialized" });
+		return toNodeHandler(auth)(req, res);
+	});
+};
+/**
+* Setup oRPC handler
+*/
+const setupRPC = (app, options) => {
+	const rpcHandler = new RPCHandler(options.rpcRouter, { interceptors: [onError((error) => {
+		console.error("[RPC Error]", error);
+	})] });
+	app.use(async (req, res, next) => {
+		if ((await rpcHandler.handle(req, res, {
+			prefix: "/rpc",
+			context: await createContext({ req })
+		})).matched) return;
+		next();
+	});
+};
+/**
+* Setup OpenAPI documentation
+*/
+const setupAPIReference = (app, options) => {
+	const apiHandler = new OpenAPIHandler(options.rpcRouter, {
+		plugins: [new OpenAPIReferencePlugin({ schemaConverters: [new ZodToJsonSchemaConverter()] })],
+		interceptors: [onError((error) => {
+			console.error("[API Reference Error]", error);
+		})]
+	});
+	app.use(async (req, res, next) => {
+		if ((await apiHandler.handle(req, res, {
+			prefix: "/api-reference",
+			context: await createContext({ req })
+		})).matched) return;
+		next();
+	});
+};
+/**
+* Setup REST routers from modules
+*/
+const setupModuleRestRouters = (app, options) => {
+	const routers = options.restRouters ?? [];
+	const sessionMiddleware = createSessionMiddleware();
+	for (const { name, router, basePath } of routers) {
+		app.use(`/api${basePath}`, express.json(), sessionMiddleware, router);
+		console.log(`[REST] Mounted module router: /api${basePath} (${name})`);
+	}
+};
+/**
+* Setup health check endpoint
+*/
+const setupHealth = (app, container) => {
+	app.get("/", (_req, res) => {
+		res.status(200).send("OK");
+	});
+	app.get("/health", async (_req, res) => {
+		const { dbPool } = container.cradle;
+		try {
+			const client = await dbPool.connect();
+			await client.query("SELECT 1");
+			client.release();
+			res.status(200).json({
+				status: "healthy",
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				checks: { database: "ok" }
+			});
+		} catch (error) {
+			console.error("[Health] Database check failed:", error);
+			res.status(503).json({
+				status: "unhealthy",
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				checks: { database: "failed" }
+			});
+		}
+	});
+};
+/**
+* Setup Prometheus metrics endpoint
+*/
+const setupMetrics = (app, container) => {
+	app.get("/metrics", (_req, res) => {
+		const { logger } = container.cradle;
+		const metricsText = logger.getMetrics?.() ?? "";
+		res.set("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
+		res.send(metricsText);
+	});
+};
+/**
+* Setup static file serving (production only)
+*/
+const setupStaticFiles = (app, publicDir) => {
+	if (process.env.NODE_ENV !== "production") return;
+	const dir = publicDir ?? path.join(__dirname, "public");
+	app.use(express.static(dir, {
+		maxAge: "1d",
+		etag: true,
+		setHeaders: (res) => {
+			res.setHeader("Access-Control-Allow-Origin", "*");
+		}
+	}));
+	app.get("{/*path}", (req, res, next) => {
+		if (req.path.startsWith("/api") || req.path.startsWith("/rpc") || req.path.startsWith("/auth") || req.path.startsWith("/health") || req.path.startsWith("/metrics")) return next();
+		res.sendFile(path.join(dir, "index.html"));
+	});
+};
+/**
+* Setup error handling middleware (must be last)
+*/
+const setupErrorMiddleware = (app) => {
+	app.use((err, req, res, _next) => {
+		const errorHandler = req.scope?.cradle.errorHandler;
+		if (!errorHandler) {
+			res.status(500).json({
+				code: "INTERNAL_SERVER_ERROR",
+				message: "Internal server error"
+			});
+			return;
+		}
+		const serialized = errorHandler.handle(err, {
+			path: req.path,
+			method: req.method,
+			requestId: req.scope?.cradle.requestId
+		});
+		res.status(serialized.statusCode).json(serialized);
+	});
+};
+
+//#endregion
+//#region src/express/server.ts
+/**
+* Build the root container with all modules loaded
+*/
+const buildContainer = async (options) => {
+	const config = options.loadConfig();
+	const moduleSpecs = await options.getModuleSpecs();
+	const rpcRouter = { ...appRouter };
+	const restRouters = [];
+	const container = await createKuckitContainer({ config });
+	await loadKuckitModules({
+		container,
+		env: config.env,
+		modules: moduleSpecs,
+		onApiRegistrations: (registrations) => {
+			for (const reg of registrations) if (reg.type === "rpc-router") {
+				if (rpcRouter[reg.name]) throw new Error(`Duplicate RPC router name: "${reg.name}"`);
+				rpcRouter[reg.name] = reg.router;
+			} else if (reg.type === "rest-router") {
+				const basePath = reg.prefix ?? `/${reg.name}`;
+				restRouters.push({
+					name: reg.name,
+					router: reg.router,
+					basePath
+				});
+			}
+			container.resolve("logger").info(`Loaded ${registrations.length} API registrations from modules`);
+		},
+		onComplete: () => {
+			container.resolve("logger").info("All modules loaded successfully");
+		}
+	});
+	return {
+		container,
+		rpcRouter,
+		restRouters
+	};
+};
+/**
+* Cleanup container resources
+*/
+const disposeContainer = async (container) => {
+	const { dbPool } = container.cradle;
+	if (dbPool && typeof dbPool.end === "function") await dbPool.end();
+};
+/**
+* Create a Kuckit server without starting it.
+* Useful for testing or when you need access to the app/container before listening.
+*/
+const createKuckitServer = async (options) => {
+	const config = options.loadConfig();
+	const { container, rpcRouter, restRouters } = await buildContainer(options);
+	const app = createKuckitApp({ config });
+	await options.hooks?.onAppCreated?.(app);
+	setupContainerMiddleware(app, container);
+	await options.hooks?.onContainerReady?.(container);
+	const routeOptions = {
+		rpcRouter,
+		restRouters
+	};
+	setupAuth(app);
+	setupRPC(app, routeOptions);
+	setupAPIReference(app, routeOptions);
+	setupModuleRestRouters(app, routeOptions);
+	setupMetrics(app, container);
+	setupHealth(app, container);
+	setupStaticFiles(app);
+	await options.hooks?.onRoutesReady?.(app, container);
+	setupErrorMiddleware(app);
+	const start = async () => {
+		const port = config.port;
+		return new Promise((resolve) => {
+			const server = app.listen(port, () => {
+				const logger = container.resolve("logger");
+				logger.info(`Server is running on port ${port}`);
+				options.hooks?.onServerReady?.(port, container);
+				const shutdown = async () => {
+					logger.info("Shutting down gracefully...");
+					await options.hooks?.onShutdown?.(container);
+					server.close(async () => {
+						await disposeContainer(container);
+						logger.info("Server closed");
+						process.exit(0);
+					});
+					setTimeout(() => {
+						logger.error("Forced shutdown");
+						process.exit(1);
+					}, 1e4);
+				};
+				process.on("SIGTERM", shutdown);
+				process.on("SIGINT", shutdown);
+				resolve({
+					port,
+					close: async () => {
+						await options.hooks?.onShutdown?.(container);
+						return new Promise((res) => {
+							server.close(async () => {
+								await disposeContainer(container);
+								res();
+							});
+						});
+					}
+				});
+			});
+		});
+	};
+	return {
+		app,
+		container,
+		start
+	};
+};
+/**
+* Run a Kuckit server - the main entry point for server applications.
+* Creates the server and immediately starts listening.
+*/
+const runKuckitServer = async (options) => {
+	return (await createKuckitServer(options)).start();
+};
+/**
+* Create a headless Kuckit context (DI container only, no Express app).
+* Useful for CLI tools, scripts, testing, or background workers.
+*/
+const createKuckitContext = async (options) => {
+	const { container } = await buildContainer(options);
+	return {
+		container,
+		dispose: () => disposeContainer(container)
+	};
+};
+
+//#endregion
+export { createKuckitApp, createKuckitContext, createKuckitServer, disposeContainer, runKuckitServer, setupAPIReference, setupAuth, setupContainerMiddleware, setupErrorMiddleware, setupHealth, setupMetrics, setupModuleRestRouters, setupRPC, setupStaticFiles };

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "@kuckit/app-server",
+	"version": "2.0.1",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"default": "./src/*.ts"
+		}
+	},
+	"publishConfig": {
+		"main": "dist/index.js",
+		"types": "dist/index.d.ts",
+		"exports": {
+			".": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"./*": {
+				"types": "./dist/*.d.ts",
+				"default": "./dist/*.js"
+			}
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"check-types": "tsc -b"
+	},
+	"dependencies": {
+		"@kuckit/sdk": "workspace:*",
+		"@kuckit/api": "workspace:*",
+		"@kuckit/db": "workspace:*",
+		"@kuckit/domain": "workspace:*",
+		"@kuckit/infrastructure": "workspace:*",
+		"@kuckit/auth": "workspace:*",
+		"express": "^5.1.0",
+		"cors": "^2.8.5",
+		"awilix": "^12.0.5",
+		"@orpc/server": "catalog:",
+		"@orpc/openapi": "catalog:",
+		"better-auth": "catalog:",
+		"pg": "^8.11.3"
+	},
+	"devDependencies": {
+		"typescript": "catalog:",
+		"@types/express": "catalog:",
+		"@types/cors": "^2.8.17",
+		"@types/pg": "^8.10.9",
+		"tsdown": "catalog:"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Main entry points
+export {
+	runKuckitServer,
+	createKuckitServer,
+	createKuckitContext,
+	disposeContainer,
+} from './express/server'
+
+// Express utilities
+export { createKuckitApp, type CreateAppOptions } from './express/app'
+export { setupContainerMiddleware } from './express/middleware'
+
+// Route setup functions (for custom wiring)
+export {
+	setupAuth,
+	setupRPC,
+	setupAPIReference,
+	setupModuleRestRouters,
+	setupHealth,
+	setupMetrics,
+	setupStaticFiles,
+	setupErrorMiddleware,
+	type SetupRoutesOptions,
+} from './express/routes'
+
+// Types
+export type {
+	KuckitServerConfig,
+	KuckitServerCradle,
+	KuckitContainer,
+	KuckitServerOptions,
+	KuckitServerHooks,
+	KuckitServer,
+	KuckitContext,
+	KuckitRequest,
+	KuckitMiddleware,
+} from './types'