@meridianjs/framework 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+import http from 'node:http';
+import { Express, RequestHandler, Request, Response, NextFunction } from 'express';
+import { MeridianContainer, MeridianConfig, ModuleConfig, ModuleDefinition, PluginConfig, ILogger } from '@meridianjs/types';
+import * as express_rate_limit from 'express-rate-limit';
+import { ZodSchema } from 'zod';
+export { asClass, asFunction, asValue } from 'awilix';
+
+interface BootstrapOptions {
+    /** Absolute path to the project root directory */
+    rootDir: string;
+    /** Path to meridian.config.ts — defaults to <rootDir>/meridian.config.ts */
+    configPath?: string;
+}
+interface MeridianApp {
+    container: MeridianContainer;
+    server: Express;
+    httpServer: http.Server;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Bootstraps a Meridian application.
+ *
+ * Order of operations:
+ *  1. Load meridian.config.ts
+ *  2. Create global DI container
+ *  3. Register core primitives (logger, config)
+ *  4. Register infrastructure modules (event bus, scheduler)
+ *  5. Load domain modules from config.modules[]
+ *  6. Load plugins from config.plugins[]
+ *  7. Load module links from src/links/
+ *  8. Create Express server
+ *  9. Apply middlewares from src/api/middlewares.ts
+ * 10. Load file-based API routes from src/api/
+ * 11. Load subscribers from src/subscribers/
+ * 12. Load scheduled jobs from src/jobs/
+ */
+declare function bootstrap(opts: BootstrapOptions): Promise<MeridianApp>;
+
+declare function createMeridianContainer(): MeridianContainer;
+
+/**
+ * Loads and validates the user's meridian.config.ts (or .js / .mjs) file.
+ * Supports both ESM and CJS projects.
+ */
+declare function loadConfig(rootDir: string, configPath?: string): Promise<MeridianConfig>;
+
+/**
+ * Type-safe helper for defining a Meridian configuration.
+ * Returns the config unchanged — purely for IDE autocomplete and type checking.
+ *
+ * @example
+ * // meridian.config.ts
+ * import { defineConfig } from "@meridianjs/framework"
+ *
+ * export default defineConfig({
+ *   projectConfig: {
+ *     databaseUrl: process.env.DATABASE_URL!,
+ *     jwtSecret: process.env.JWT_SECRET!,
+ *   },
+ *   modules: [
+ *     { resolve: "@meridianjs/user" },
+ *     { resolve: "@meridianjs/project" },
+ *   ],
+ * })
+ */
+declare function defineConfig(config: MeridianConfig): MeridianConfig;
+
+interface MiddlewareRoute {
+    matcher: string | RegExp;
+    middlewares: RequestHandler[];
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "ALL";
+}
+interface MiddlewaresConfig {
+    routes: MiddlewareRoute[];
+}
+/**
+ * Type-safe helper for defining API middleware configuration.
+ *
+ * @example
+ * // src/api/middlewares.ts
+ * import { defineMiddlewares } from "@meridianjs/framework"
+ * import { authenticateJWT } from "@meridianjs/auth"
+ *
+ * export default defineMiddlewares({
+ *   routes: [
+ *     { matcher: "/admin*", middlewares: [authenticateJWT()] },
+ *   ],
+ * })
+ */
+declare function defineMiddlewares(config: MiddlewaresConfig): MiddlewaresConfig;
+
+/**
+ * Loads all modules declared in the config's modules[] array.
+ *
+ * Each module gets its own isolated child container (Awilix scope).
+ * Internal services (e.g. sub-services) remain private to the module.
+ * Only the module's main service is promoted to the global container.
+ */
+declare function loadModules(globalContainer: MeridianContainer, moduleConfigs: ModuleConfig[], rootDir: string): Promise<void>;
+declare function resolveModuleDefinition(config: ModuleConfig, rootDir: string): Promise<ModuleDefinition>;
+
+/**
+ * Scans src/api/ recursively for route.ts files and registers them on Express.
+ *
+ * File path → Express route:
+ *   src/api/admin/projects/route.ts       → /admin/projects
+ *   src/api/admin/projects/[id]/route.ts  → /admin/projects/:id
+ *   src/api/store/products/route.ts       → /store/products
+ *
+ * Each route.ts exports named HTTP method handlers:
+ *   export const GET = async (req, res) => { ... }
+ *   export const POST = async (req, res) => { ... }
+ */
+declare function loadRoutes(app: Express, container: MeridianContainer, apiDir: string): Promise<void>;
+
+/**
+ * Scans src/subscribers/ for subscriber files and registers them on the event bus.
+ *
+ * Each subscriber file must export:
+ *   - default: async function handler({ event, container }) { ... }
+ *   - config: { event: "event.name" | string[] }
+ */
+declare function loadSubscribers(container: MeridianContainer, subscribersDir: string): Promise<void>;
+
+/**
+ * Scans src/jobs/ for scheduled job files and registers them with the scheduler.
+ *
+ * Each job file must export:
+ *   - default: async function(container) { ... }
+ *   - config: { name: string, schedule: string | { interval: number } }
+ */
+declare function loadJobs(container: MeridianContainer, jobsDir: string): Promise<void>;
+
+/**
+ * Scans src/links/ for link definition files, registers a LinkService and
+ * a Query service in the global container.
+ *
+ * Link files export a default LinkDefinition created with defineLink().
+ */
+declare function loadLinks(container: MeridianContainer, linksDir: string): Promise<void>;
+
+/**
+ * Loads plugins declared in config.plugins[].
+ *
+ * Plugin package contract:
+ *  - Default export: async register(ctx: PluginRegistrationContext) — optional
+ *  - Named export `pluginRoot`: string — path to the directory containing
+ *    the plugin's api/, subscribers/, jobs/ sub-directories.
+ *    In production (compiled): points to the plugin's dist/ dir.
+ *    In development (tsx): points to the plugin's src/ dir.
+ *
+ * Auto-scan order when `pluginRoot` is NOT exported:
+ *  1. <packageRoot>/dist/   — built output
+ *  2. <packageRoot>/src/    — TypeScript source (dev with tsx)
+ *  3. <resolvedPath>/       — local path plugins
+ *
+ * Supported resolve values in config:
+ *  - npm package name: "@my-org/meridian-github"
+ *  - relative local path: "./src/plugins/my-plugin"
+ *  - absolute path: "/absolute/path/to/plugin"
+ */
+declare function loadPlugins(container: MeridianContainer, plugins: PluginConfig[], rootDir: string): Promise<void>;
+
+declare class ConsoleLogger implements ILogger {
+    private readonly prefix;
+    constructor(prefix?: string);
+    private format;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+
+declare function createServer(container: MeridianContainer, config: MeridianConfig): Express;
+
+/** Strict limiter for auth endpoints: 10 requests per minute per IP. */
+declare const authRateLimit: express_rate_limit.RateLimitRequestHandler;
+/** General API limiter: 300 requests per minute per IP. */
+declare const apiRateLimit: express_rate_limit.RateLimitRequestHandler;
+
+/**
+ * Express middleware that validates `req.body` against a Zod schema.
+ *
+ * On success, replaces `req.body` with the parsed (coerced/stripped) value
+ * and calls `next()`.
+ * On failure, responds 400 with a structured error including per-field details.
+ *
+ * @example
+ * const loginSchema = z.object({ email: z.string().email(), password: z.string().min(1) })
+ * export const POST = [validate(loginSchema), handler]
+ */
+declare function validate(schema: ZodSchema): (req: Request, res: Response, next: NextFunction) => void;
+
+export { type BootstrapOptions, ConsoleLogger, type MeridianApp, type MiddlewareRoute, type MiddlewaresConfig, apiRateLimit, authRateLimit, bootstrap, createMeridianContainer, createServer, defineConfig, defineMiddlewares, loadConfig, loadJobs, loadLinks, loadModules, loadPlugins, loadRoutes, loadSubscribers, resolveModuleDefinition, validate };

package/dist/index.js

@@ -0,0 +1,735 @@
+// src/bootstrap.ts
+import path8 from "path";
+import http from "http";
+
+// src/container.ts
+import {
+  createContainer,
+  asValue,
+  asClass,
+  asFunction,
+  InjectionMode
+} from "awilix";
+function wrapContainer(raw) {
+  const container = {
+    resolve(token) {
+      return raw.resolve(token);
+    },
+    register(registrations) {
+      const awilixRegs = {};
+      for (const [key, value] of Object.entries(registrations)) {
+        if (value === null || value === void 0) {
+          awilixRegs[key] = asValue(value);
+        } else if (typeof value === "function" && value.prototype && Object.getOwnPropertyNames(value.prototype).length > 1) {
+          awilixRegs[key] = asClass(value, { lifetime: "SINGLETON" });
+        } else if (typeof value === "function") {
+          awilixRegs[key] = asFunction(value, { lifetime: "SINGLETON" });
+        } else {
+          awilixRegs[key] = asValue(value);
+        }
+      }
+      raw.register(awilixRegs);
+    },
+    createScope() {
+      return wrapContainer(raw.createScope());
+    }
+  };
+  return container;
+}
+function createMeridianContainer() {
+  const raw = createContainer({
+    injectionMode: InjectionMode.PROXY,
+    strict: false
+  });
+  return wrapContainer(raw);
+}
+
+// src/config-loader.ts
+import path from "path";
+import { pathToFileURL } from "url";
+async function loadConfig(rootDir, configPath) {
+  const resolvedPath = configPath ?? path.join(rootDir, "meridian.config.ts");
+  const candidates = configPath ? [resolvedPath] : [
+    path.join(rootDir, "meridian.config.ts"),
+    path.join(rootDir, "meridian.config.mts"),
+    path.join(rootDir, "meridian.config.js"),
+    path.join(rootDir, "meridian.config.mjs"),
+    path.join(rootDir, "meridian.config.cjs")
+  ];
+  let config = null;
+  for (const candidate of candidates) {
+    try {
+      const mod = await import(pathToFileURL(candidate).href);
+      const raw = mod.default ?? mod;
+      config = raw;
+      break;
+    } catch (err) {
+      if (err.code !== "ERR_MODULE_NOT_FOUND" && err.code !== "MODULE_NOT_FOUND") {
+        throw new Error(
+          `Failed to load Meridian config from "${candidate}": ${err.message}`
+        );
+      }
+    }
+  }
+  if (!config) {
+    throw new Error(
+      `Could not find meridian.config.ts in "${rootDir}". Make sure you have a meridian.config.ts file in your project root.`
+    );
+  }
+  validateConfig(config);
+  return config;
+}
+function validateConfig(config) {
+  if (!config.projectConfig) {
+    throw new Error("meridian.config: missing required field 'projectConfig'");
+  }
+  if (!config.projectConfig.databaseUrl) {
+    throw new Error("meridian.config.projectConfig: missing required field 'databaseUrl'");
+  }
+  if (!config.projectConfig.jwtSecret) {
+    throw new Error("meridian.config.projectConfig: missing required field 'jwtSecret'");
+  }
+}
+
+// src/module-loader.ts
+import path2 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+async function loadModules(globalContainer, moduleConfigs, rootDir) {
+  const logger = globalContainer.resolve("logger");
+  for (const moduleConfig of moduleConfigs) {
+    const definition = await resolveModuleDefinition(moduleConfig, rootDir);
+    logger.info(`Loading module: ${definition.key}`);
+    const moduleContainer = globalContainer.createScope();
+    const moduleOptions = moduleConfig.options ?? {};
+    moduleContainer.register({
+      moduleOptions,
+      logger
+    });
+    if (definition.loaders) {
+      for (const loader of definition.loaders) {
+        await loader({
+          container: moduleContainer,
+          options: moduleConfig.options,
+          logger
+        });
+      }
+    }
+    const ServiceClass = definition.service;
+    const serviceInstance = new ServiceClass(moduleContainer);
+    moduleContainer.register({ [definition.key]: serviceInstance });
+    globalContainer.register({ [definition.key]: serviceInstance });
+    logger.info(`Module loaded: ${definition.key}`);
+  }
+}
+async function resolveModuleDefinition(config, rootDir) {
+  if (typeof config.resolve === "object" && config.resolve !== null) {
+    return config.resolve;
+  }
+  const resolveStr = config.resolve;
+  const importPath = resolveStr.startsWith(".") ? pathToFileURL2(path2.resolve(rootDir, resolveStr)).href : resolveStr;
+  const mod = await import(importPath);
+  const definition = mod.default ?? mod;
+  if (!definition?.key || !definition?.service) {
+    throw new Error(
+      `Module at "${resolveStr}" must export a ModuleDefinition with 'key' and 'service'. Use the Module() helper from @meridianjs/framework-utils.`
+    );
+  }
+  return definition;
+}
+
+// src/plugin-loader.ts
+import path6 from "path";
+import fs4 from "fs/promises";
+import { pathToFileURL as pathToFileURL6 } from "url";
+import { createRequire } from "module";
+
+// src/route-loader.ts
+import fs from "fs/promises";
+import path3 from "path";
+import { pathToFileURL as pathToFileURL3 } from "url";
+import { Router } from "express";
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+async function loadRoutes(app, container, apiDir) {
+  const logger = container.resolve("logger");
+  try {
+    await fs.access(apiDir);
+  } catch {
+    logger.debug(`No API directory found at ${apiDir}, skipping route loading.`);
+    return;
+  }
+  const router = Router();
+  await scanApiDir(router, apiDir, apiDir, logger);
+  app.use("/", router);
+}
+function sortEntriesForRouteOrder(entries) {
+  return [...entries].sort((a, b) => {
+    const aParam = a.startsWith("[") ? 1 : 0;
+    const bParam = b.startsWith("[") ? 1 : 0;
+    return aParam - bParam;
+  });
+}
+async function scanApiDir(router, dir, baseDir, logger) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return;
+  }
+  const sorted = sortEntriesForRouteOrder(entries);
+  for (const entry of sorted) {
+    const fullPath = path3.join(dir, entry);
+    const stat = await fs.stat(fullPath);
+    if (stat.isDirectory()) {
+      await scanApiDir(router, fullPath, baseDir, logger);
+      continue;
+    }
+    if (!/^route\.(ts|mts|js|mjs|cjs)$/.test(entry)) continue;
+    const routePath = filePathToRoutePath(fullPath, baseDir);
+    let routeModule;
+    try {
+      routeModule = await import(pathToFileURL3(fullPath).href);
+    } catch (err) {
+      logger.error(`Failed to load route file ${fullPath}: ${err.message}`);
+      continue;
+    }
+    let registeredCount = 0;
+    for (const method of HTTP_METHODS) {
+      const handler = routeModule[method];
+      if (typeof handler !== "function") continue;
+      const expressMethod = method.toLowerCase();
+      router[expressMethod](
+        routePath,
+        async (req, res, next) => {
+          try {
+            await handler(req, res, next);
+          } catch (err) {
+            next(err);
+          }
+        }
+      );
+      registeredCount++;
+    }
+    const middlewares = routeModule["middlewares"];
+    if (Array.isArray(middlewares)) {
+      router.use(routePath, ...middlewares);
+    }
+    if (registeredCount > 0) {
+      logger.debug(`Registered route: ${routePath} [${Object.keys(routeModule).filter((k) => HTTP_METHODS.includes(k)).join(", ")}]`);
+    }
+  }
+}
+function filePathToRoutePath(filePath, baseDir) {
+  const relative = path3.relative(baseDir, filePath);
+  const withoutFile = relative.replace(/[/\\]?route\.(ts|mts|js|mjs|cjs)$/, "");
+  const normalized = withoutFile.replace(/\\/g, "/");
+  const withParams = normalized.replace(/\[(\w+)\]/g, ":$1");
+  return withParams ? `/${withParams}` : "/";
+}
+
+// src/subscriber-loader.ts
+import fs2 from "fs/promises";
+import path4 from "path";
+import { pathToFileURL as pathToFileURL4 } from "url";
+async function loadSubscribers(container, subscribersDir) {
+  const logger = container.resolve("logger");
+  try {
+    await fs2.access(subscribersDir);
+  } catch {
+    logger.debug(`No subscribers directory at ${subscribersDir}, skipping.`);
+    return;
+  }
+  const eventBus = container.resolve("eventBus");
+  const files = await fs2.readdir(subscribersDir);
+  for (const file of files) {
+    if (!/\.(ts|mts|js|mjs|cjs)$/.test(file)) continue;
+    const fullPath = path4.join(subscribersDir, file);
+    let mod;
+    try {
+      mod = await import(pathToFileURL4(fullPath).href);
+    } catch (err) {
+      logger.error(`Failed to load subscriber ${file}: ${err.message}`);
+      continue;
+    }
+    const handler = mod.default;
+    const config = mod.config;
+    if (typeof handler !== "function") {
+      logger.warn(`Subscriber ${file} is missing a default export function.`);
+      continue;
+    }
+    if (!config?.event) {
+      logger.warn(`Subscriber ${file} is missing a config.event export.`);
+      continue;
+    }
+    const events = Array.isArray(config.event) ? config.event : [config.event];
+    for (const eventName of events) {
+      eventBus.subscribe(
+        eventName,
+        (args) => handler({ ...args, container })
+      );
+      logger.debug(`Subscriber registered: ${file} \u2192 ${eventName}`);
+    }
+  }
+}
+
+// src/job-loader.ts
+import fs3 from "fs/promises";
+import path5 from "path";
+import { pathToFileURL as pathToFileURL5 } from "url";
+async function loadJobs(container, jobsDir) {
+  const logger = container.resolve("logger");
+  let scheduler = null;
+  try {
+    scheduler = container.resolve("scheduler");
+  } catch {
+    logger.debug("No scheduler registered, skipping job loading.");
+    return;
+  }
+  try {
+    await fs3.access(jobsDir);
+  } catch {
+    logger.debug(`No jobs directory at ${jobsDir}, skipping.`);
+    return;
+  }
+  const files = await fs3.readdir(jobsDir);
+  for (const file of files) {
+    if (!/\.(ts|mts|js|mjs|cjs)$/.test(file)) continue;
+    const fullPath = path5.join(jobsDir, file);
+    let mod;
+    try {
+      mod = await import(pathToFileURL5(fullPath).href);
+    } catch (err) {
+      logger.error(`Failed to load job ${file}: ${err.message}`);
+      continue;
+    }
+    const fn = mod.default;
+    const config = mod.config;
+    if (typeof fn !== "function") {
+      logger.warn(`Job ${file} is missing a default export function.`);
+      continue;
+    }
+    if (!config?.name || !config?.schedule) {
+      logger.warn(`Job ${file} is missing a valid config export.`);
+      continue;
+    }
+    await scheduler.register(config, () => fn(container));
+    logger.info(`Scheduled job registered: ${config.name} (${JSON.stringify(config.schedule)})`);
+  }
+}
+
+// src/plugin-loader.ts
+async function loadPlugins(container, plugins, rootDir) {
+  const logger = container.resolve("logger");
+  for (const plugin of plugins) {
+    logger.info(`Loading plugin: ${plugin.resolve}`);
+    const isLocalPath = plugin.resolve.startsWith(".") || path6.isAbsolute(plugin.resolve);
+    const importPath = isLocalPath ? pathToFileURL6(path6.resolve(rootDir, plugin.resolve)).href : plugin.resolve;
+    let pluginMod;
+    try {
+      pluginMod = await import(importPath);
+    } catch (err) {
+      logger.error(`Failed to load plugin "${plugin.resolve}": ${err.message}`);
+      continue;
+    }
+    let scanRoot = null;
+    if (pluginMod.pluginRoot && typeof pluginMod.pluginRoot === "string") {
+      scanRoot = pluginMod.pluginRoot;
+    } else if (isLocalPath) {
+      const resolvedPath = path6.resolve(rootDir, plugin.resolve);
+      try {
+        const stat = await fs4.stat(resolvedPath);
+        scanRoot = stat.isDirectory() ? resolvedPath : path6.dirname(resolvedPath);
+      } catch {
+        scanRoot = path6.dirname(resolvedPath);
+      }
+    } else {
+      scanRoot = resolveNpmPackageRoot(plugin.resolve, rootDir);
+    }
+    const ctx = {
+      container,
+      pluginOptions: plugin.options ?? {},
+      addModule: async (moduleConfig) => {
+        await loadModules(container, [moduleConfig], scanRoot ?? rootDir);
+      }
+    };
+    if (typeof pluginMod.default === "function") {
+      try {
+        await pluginMod.default(ctx);
+      } catch (err) {
+        logger.error(`Plugin register() failed for "${plugin.resolve}": ${err.message}`);
+        continue;
+      }
+    }
+    if (scanRoot) {
+      await autoScanPlugin(scanRoot, container, logger);
+    }
+    logger.info(`Plugin loaded: ${plugin.resolve}`);
+  }
+}
+async function autoScanPlugin(scanRoot, container, logger) {
+  const server = container.resolve("server");
+  const candidates = [
+    scanRoot,
+    // pluginRoot already points to compiled dir
+    path6.join(scanRoot, "dist"),
+    // package root → try dist/ first
+    path6.join(scanRoot, "src")
+    // package root → try src/ (tsx dev mode)
+  ];
+  for (const candidate of candidates) {
+    const apiDir = path6.join(candidate, "api");
+    try {
+      await fs4.access(apiDir);
+      await Promise.all([
+        loadRoutes(server, container, apiDir),
+        loadSubscribers(container, path6.join(candidate, "subscribers")),
+        loadJobs(container, path6.join(candidate, "jobs"))
+      ]);
+      logger.debug(`Plugin auto-scanned from: ${candidate}`);
+      return;
+    } catch {
+    }
+  }
+  logger.debug(`No api/ directory found for plugin scan root: ${scanRoot}`);
+}
+function resolveNpmPackageRoot(packageName, fromDir) {
+  try {
+    const require2 = createRequire(path6.join(fromDir, "synthetic.cjs"));
+    const pkgJsonPath = require2.resolve(`${packageName}/package.json`);
+    return path6.dirname(pkgJsonPath);
+  } catch {
+    try {
+      const require2 = createRequire(path6.join(fromDir, "synthetic.cjs"));
+      const mainPath = require2.resolve(packageName);
+      let dir = path6.dirname(mainPath);
+      while (dir !== path6.dirname(dir)) {
+        try {
+          require2.resolve(path6.join(dir, "package.json"));
+          return dir;
+        } catch {
+          dir = path6.dirname(dir);
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+}
+
+// src/link-loader.ts
+import fs5 from "fs/promises";
+import path7 from "path";
+import { pathToFileURL as pathToFileURL7 } from "url";
+async function loadLinks(container, linksDir) {
+  const logger = container.resolve("logger");
+  const definitions = [];
+  try {
+    await fs5.access(linksDir);
+  } catch {
+    logger.debug(`No links directory at ${linksDir}, skipping.`);
+    registerEmptyServices(container);
+    return;
+  }
+  const files = await fs5.readdir(linksDir);
+  for (const file of files) {
+    if (!/\.(ts|mts|js|mjs|cjs)$/.test(file)) continue;
+    const fullPath = path7.join(linksDir, file);
+    let mod;
+    try {
+      mod = await import(pathToFileURL7(fullPath).href);
+    } catch (err) {
+      logger.error(`Failed to load link file ${file}: ${err.message}`);
+      continue;
+    }
+    const def = mod.default;
+    if (def?.linkTableName) {
+      definitions.push(def);
+      logger.debug(`Link loaded: ${def.linkTableName}`);
+    }
+  }
+  const linkService = new LinkService(definitions, container, logger);
+  const queryService = new QueryService(definitions, container, logger);
+  container.register({
+    link: linkService,
+    query: queryService
+  });
+  logger.info(`Loaded ${definitions.length} module link(s)`);
+}
+function registerEmptyServices(container) {
+  const link = new LinkService([], container, null);
+  const query = new QueryService([], container, null);
+  container.register({ link, query });
+}
+var LinkService = class {
+  constructor(defs, container, logger) {
+    this.defs = defs;
+    this.container = container;
+    this.logger = logger;
+    this.defsByTable = new Map(defs.map((d) => [d.linkTableName, d]));
+  }
+  defsByTable;
+  async create(linkTableName, leftId, rightId, data) {
+    this.logger?.debug(`Link.create: ${linkTableName} ${leftId} \u2192 ${rightId}`);
+  }
+  async dismiss(linkTableName, leftId, rightId) {
+    this.logger?.debug(`Link.dismiss: ${linkTableName} ${leftId} \u2192 ${rightId}`);
+  }
+  getDefinitions() {
+    return this.defs;
+  }
+};
+var QueryService = class {
+  constructor(defs, container, logger) {
+    this.defs = defs;
+    this.container = container;
+    this.logger = logger;
+  }
+  async graph(options) {
+    this.logger?.debug(`Query.graph: ${options.entity}`, { fields: options.fields });
+    return { data: [] };
+  }
+};
+
+// src/server.ts
+import express from "express";
+import cors from "cors";
+import helmet from "helmet";
+function createServer(container, config) {
+  const app = express();
+  const logger = container.resolve("logger");
+  app.use(express.json({ limit: "10mb" }));
+  app.use(express.urlencoded({ extended: true, limit: "10mb" }));
+  app.use(helmet({
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        imgSrc: ["'self'", "data:", "blob:"],
+        connectSrc: ["'self'"]
+      }
+    },
+    crossOriginEmbedderPolicy: false
+  }));
+  const corsOrigin = config.projectConfig.cors?.origin ?? "*";
+  if (corsOrigin === "*" && process.env.NODE_ENV === "production") {
+    logger.warn(
+      "CORS origin is set to '*' in production. Set projectConfig.cors.origin to a specific domain to restrict cross-origin access."
+    );
+  }
+  app.use(
+    cors({
+      origin: corsOrigin,
+      credentials: config.projectConfig.cors?.credentials ?? false,
+      methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+      allowedHeaders: ["Content-Type", "Authorization"],
+      exposedHeaders: ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"]
+    })
+  );
+  app.use((req, _res, next) => {
+    req.scope = container.createScope();
+    next();
+  });
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+  });
+  app.get("/ready", (_req, res) => {
+    res.json({ ok: true });
+  });
+  app.use((err, _req, res, _next) => {
+    const status = err.status ?? err.statusCode ?? 500;
+    const message = err.message ?? "Internal Server Error";
+    if (status >= 500) {
+      logger.error(`Unhandled error: ${message}`, {
+        stack: err.stack,
+        status
+      });
+    }
+    res.status(status).json({
+      error: {
+        message,
+        type: err.type ?? err.name ?? "Error",
+        ...process.env.NODE_ENV === "development" && { stack: err.stack }
+      }
+    });
+  });
+  return app;
+}
+
+// src/logger.ts
+var ConsoleLogger = class {
+  constructor(prefix = "meridian") {
+    this.prefix = prefix;
+  }
+  format(level, message, meta) {
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    const base = `[${ts}] [${level.toUpperCase()}] [${this.prefix}] ${message}`;
+    return meta ? `${base} ${JSON.stringify(meta)}` : base;
+  }
+  info(message, meta) {
+    console.log(this.format("info", message, meta));
+  }
+  warn(message, meta) {
+    console.warn(this.format("warn", message, meta));
+  }
+  error(message, meta) {
+    console.error(this.format("error", message, meta));
+  }
+  debug(message, meta) {
+    if (process.env.DEBUG) {
+      console.debug(this.format("debug", message, meta));
+    }
+  }
+};
+
+// src/bootstrap.ts
+async function bootstrap(opts) {
+  const { rootDir } = opts;
+  const config = await loadConfig(rootDir, opts.configPath);
+  const container = createMeridianContainer();
+  const logger = new ConsoleLogger("meridian");
+  container.register({
+    logger,
+    config
+  });
+  logger.info("Bootstrapping Meridian application...");
+  await loadModules(container, config.modules ?? [], rootDir);
+  let eventBus;
+  try {
+    eventBus = container.resolve("eventBus");
+  } catch {
+    logger.warn(
+      "No eventBus module registered. Events will not be dispatched. Add @meridianjs/event-bus-local or @meridianjs/event-bus-redis to your config.modules."
+    );
+    eventBus = {
+      async emit() {
+      },
+      subscribe() {
+      },
+      unsubscribe() {
+      }
+    };
+    container.register({ eventBus });
+  }
+  await loadPlugins(container, config.plugins ?? [], rootDir);
+  await loadLinks(container, path8.join(rootDir, "src", "links"));
+  const server = createServer(container, config);
+  container.register({ server });
+  await loadMiddlewares(server, container, path8.join(rootDir, "src", "api"));
+  await loadRoutes(server, container, path8.join(rootDir, "src", "api"));
+  await loadSubscribers(container, path8.join(rootDir, "src", "subscribers"));
+  await loadJobs(container, path8.join(rootDir, "src", "jobs"));
+  const httpServer = http.createServer(server);
+  logger.info("Meridian application bootstrapped successfully.");
+  return {
+    container,
+    server,
+    httpServer,
+    async start() {
+      const port = config.projectConfig.httpPort ?? 9e3;
+      await new Promise((resolve, reject) => {
+        httpServer.listen(port, () => {
+          logger.info(`Meridian server running on http://localhost:${port}`);
+          resolve();
+        });
+        httpServer.on("error", reject);
+      });
+    },
+    async stop() {
+      logger.info("Shutting down Meridian server...");
+      await new Promise((resolve, reject) => {
+        httpServer.close((err) => err ? reject(err) : resolve());
+      });
+      try {
+        const bus = container.resolve("eventBus");
+        await bus.close?.();
+      } catch {
+      }
+      logger.info("Meridian server stopped.");
+    }
+  };
+}
+async function loadMiddlewares(server, container, apiDir) {
+  const logger = container.resolve("logger");
+  const middlewaresPath = path8.join(apiDir, "middlewares.ts");
+  let mod;
+  try {
+    const { pathToFileURL: pathToFileURL8 } = await import("url");
+    mod = await import(pathToFileURL8(middlewaresPath).href);
+  } catch {
+    return;
+  }
+  const config = mod.default;
+  if (!config?.routes) return;
+  for (const route of config.routes) {
+    server.use(route.matcher, ...route.middlewares);
+    logger.debug(`Middleware applied: ${route.matcher}`);
+  }
+}
+
+// src/utils/define-config.ts
+function defineConfig(config) {
+  return config;
+}
+
+// src/utils/define-middlewares.ts
+function defineMiddlewares(config) {
+  return config;
+}
+
+// src/rate-limit.ts
+import rateLimit from "express-rate-limit";
+var sharedOpts = {
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: { message: "Too many requests" } }
+};
+var authRateLimit = rateLimit({
+  windowMs: 6e4,
+  max: 10,
+  ...sharedOpts
+});
+var apiRateLimit = rateLimit({
+  windowMs: 6e4,
+  max: 300,
+  ...sharedOpts
+});
+
+// src/validate.ts
+function validate(schema) {
+  return (req, res, next) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      res.status(400).json({
+        error: {
+          message: "Validation error",
+          details: result.error.flatten().fieldErrors
+        }
+      });
+      return;
+    }
+    req.body = result.data;
+    next();
+  };
+}
+export {
+  ConsoleLogger,
+  apiRateLimit,
+  asClass,
+  asFunction,
+  asValue,
+  authRateLimit,
+  bootstrap,
+  createMeridianContainer,
+  createServer,
+  defineConfig,
+  defineMiddlewares,
+  loadConfig,
+  loadJobs,
+  loadLinks,
+  loadModules,
+  loadPlugins,
+  loadRoutes,
+  loadSubscribers,
+  resolveModuleDefinition,
+  validate
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@meridianjs/framework",
+  "version": "0.1.0",
+  "description": "Core Meridian framework: bootstrap, DI container, module/route/subscriber/job loaders",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@meridianjs/framework-utils": "^0.1.0",
+    "@meridianjs/types": "^0.1.0",
+    "awilix": "^12.0.5",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "express-rate-limit": "^7.5.0",
+    "helmet": "^8.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "tsup": "^8.3.5",
+    "tsx": "4.21.0",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}