@mindbase/express-common 1.0.7 → 1.0.9

package/commands/prepare.ts

@@ -0,0 +1,62 @@
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+import { ScanResult } from "../feature/scanner/FileScanner";
+
+/**
+ * 生成 .drizzle-schemas.json 文件
+ * @param scannedResults 扫描结果
+ * @param cwd 当前工作目录
+ */
+export function generateDrizzleSchemasJson(
+  scannedResults: ScanResult[],
+  cwd: string = process.cwd()
+): void {
+  // 过滤 ORM schema（路径包含 /orm/）
+  const ormSchemaFiles = scannedResults
+    .filter((r) => r.type === "schema" && r.filePath.includes("/orm/"))
+    .map((f) => path.relative(cwd, f.filePath).replace(/\\/g, "/"));
+
+  // 生成到当前工作目录（宿主项目根目录）
+  const schemaJsonPath = path.join(cwd, ".drizzle-schemas.json");
+  fs.writeFileSync(schemaJsonPath, JSON.stringify(ormSchemaFiles, null, 2));
+
+  console.log(`📄 准备模式：生成 schema 清单...`);
+  console.log(`✅ 已生成 ${ormSchemaFiles.length} 个 schema 文件路径`);
+  console.log(`📁 文件位置: ${schemaJsonPath}`);
+}
+
+/**
+ * 准备命令 - 通过环境变量控制复用宿主 app.ts
+ */
+export async function prepare(cwd: string = process.cwd()): Promise<void> {
+  console.log("🚀 MindBase 环境准备工具");
+  console.log(`工作目录: ${cwd}\n`);
+
+  const appPath = path.join(cwd, "src/app.ts");
+
+  if (!fs.existsSync(appPath)) {
+    console.error("❌ 未找到 src/app.ts");
+    process.exit(1);
+  }
+
+  try {
+    console.log("📄 加载宿主应用...");
+
+    // 设置准备模式环境变量
+    process.env.PREPARE_MODE = "true";
+
+    // 动态导入并执行宿主 app.ts
+    await import(pathToFileURL(appPath).href);
+
+    console.log("\n✅ 环境准备完成！");
+  } catch (error) {
+    console.error("\n❌ 准备失败:", error);
+    process.exit(1);
+  }
+}
+
+// 兼容旧代码：保留 precache 别名
+export async function precache(cwd?: string): Promise<void> {
+  return prepare(cwd);
+}

package/core/app.ts

@@ -0,0 +1,186 @@
+import { Express } from "express";
+import { createState } from "./state";
+import { setBaseDir, scan, addScanPath } from "../feature/scanner/FileScanner";
+import { MindBaseAppOptions } from "../types/Index";
+import initExpress from "../utils/InitExpress";
+import { setupDatabase } from "../utils/InitDatabase";
+import { registerComponents } from "../utils/ComponentRegistry";
+import { setupErrorHandlers } from "../utils/InitErrorHandler";
+import { startServer } from "../utils/HttpServer";
+import logger from "../utils/Logger";
+import { initDocManager } from "../utils/DocManager";
+import docRouter from "../routes/Doc.route";
+import { generateDrizzleSchemasJson } from "../commands/prepare";
+
+/**
+ * MindBase 应用实例
+ */
+export interface MindBaseApp {
+  /** 注册插件模块 */
+  use(plugin: any): void;
+  /** 启动应用（初始化数据库、注册路由、启动 HTTP 服务） */
+  startup(): Promise<void>;
+  /** 获取 Express 实例 */
+  getApp(): Express;
+  /** 获取 Drizzle 数据库实例 */
+  getDB(): any;
+  /** 获取应用配置选项 */
+  getOptions(): MindBaseAppOptions;
+}
+
+/**
+ * 创建 MindBase 应用实例
+ * @param options 应用配置选项
+ * @returns MindBase 应用实例
+ * @example
+ * const app = createApp({
+ *   port: 3000,
+ *   logLevel: "debug",
+ * });
+ * app.use(auth);
+ * await app.startup();
+ */
+export function createApp(options: MindBaseAppOptions = {}): MindBaseApp {
+  logger.startup("初始化", "应用初始化……");
+  const stateInstance = createState(options);
+  const plugins: any[] = [];
+
+  // 初始化日志级别
+  if (stateInstance.options.logLevel) {
+    logger.setLevel(stateInstance.options.logLevel);
+  }
+
+  const app: MindBaseApp = {
+    use: async (plugin) => {
+      if (typeof plugin.install === "function") {
+        plugins.push(plugin);
+      }
+      if (typeof plugin.__modulePath === "string") {
+        logger.startup("模块", `注册：${plugin.__modulePath}`);
+        addScanPath(plugin.__modulePath);
+      }
+    },
+    startup: async () => {
+      const isPrepareMode = process.env.PREPARE_MODE === "true";
+      // 0. 初始化 Express 基础配置
+      if (!isPrepareMode) {
+        initExpress(stateInstance);
+      }
+
+      // 1. 准备扫描环境
+      await prepareScanEnvironment();
+
+      // 2. 扫描组件
+      const scannedResults = await scanComponents();
+
+      // 准备模式：生成 schema 清单后返回，不启动服务
+      if (isPrepareMode) {
+        generateDrizzleSchemasJson(scannedResults, process.cwd());
+        return;
+      }
+
+      // 3. 初始化数据库
+      await initializeDataStorage(scannedResults);
+
+      // 4. 初始化模块
+      await installPlugins();
+
+      // 5. 注册组件
+
+      registerComponents(stateInstance, scannedResults);
+
+      // 6. 注册文档路由
+      registerDocRoutes();
+
+      // 7. 注册错误处理
+      setupErrorHandlers(stateInstance.express, stateInstance.options.logging);
+
+      // 8. 启动 HTTP 服务
+      await startHttpServer();
+
+      logger.startup("初始化", "✅ 应用启动完成");
+    },
+
+    getApp: () => stateInstance.express,
+    getDB: () => stateInstance.db,
+    getOptions: () => stateInstance.options,
+  };
+
+  // 准备扫描环境
+  async function prepareScanEnvironment() {
+    setBaseDir(process.cwd());
+    logger.startup("扫描", `基准目录: ${process.cwd()}`);
+  }
+
+  // 扫描组件
+  async function scanComponents() {
+    const scannedResults = await scan();
+
+    // 统计缓存命中情况
+    const routeFiles = scannedResults.filter((r) => r.type === "route");
+    const cacheHits = routeFiles.filter((r) => r.cacheHit).length;
+    const total = routeFiles.length;
+
+    if (cacheHits > 0) {
+      logger.startup("扫描", `发现 ${scannedResults.length} 个组件文件 (缓存命中: ${cacheHits}/${total})`);
+    } else {
+      logger.startup("扫描", `发现 ${scannedResults.length} 个组件文件`);
+    }
+
+    return scannedResults;
+  }
+
+  // 初始化数据存储
+  async function initializeDataStorage(scannedResults) {
+    // 初始化数据库与 Schema
+    setupDatabase(stateInstance, scannedResults);
+    stateInstance.express.set("db", stateInstance.db);
+
+    // 收集数据库信息
+    if (stateInstance.db) {
+      const dbPath = stateInstance.options.database?.path || "./data/app.db";
+      logger.startup("数据库", `已连接: SQLite (${dbPath})`);
+    }
+
+    // 初始化文档管理器
+    const docDbPath = stateInstance.options.database?.path
+      ? stateInstance.options.database.path.replace(/app\.db$/, "doc.db")
+      : "./data/doc.db";
+    initDocManager({ path: docDbPath });
+    logger.startup("数据库", `文档库已初始化: ${docDbPath}`);
+  }
+
+  // 执行插件安装
+  async function installPlugins() {
+    for (const plugin of plugins) {
+      await plugin.install(app);
+    }
+  }
+
+  // 启动 HTTP 服务
+  async function startHttpServer() {
+    const listenPort = stateInstance.options.port || 3000;
+    await startServer(stateInstance.express, listenPort);
+
+    // 打印服务器启动信息
+    const serverUrl = `http://${stateInstance.options.host}:${listenPort}`;
+    logger.startup("服务", `访问地址: ${serverUrl}`);
+  }
+
+  // 注册文档路由
+  function registerDocRoutes() {
+    const apiPrefix = stateInstance.options.apiPrefix || "/api";
+    const docRoutePath = `${apiPrefix}/doc`.replace(/\/+/g, "/");
+    stateInstance.express.use(docRoutePath, docRouter);
+    stateInstance.options.authWhitelist.push(`${docRoutePath}/modules`);
+    logger.startup("路由", `${docRoutePath}/modules (GET)`);
+    stateInstance.options.authWhitelist.push(`${docRoutePath}/routes`);
+    logger.startup("路由", `${docRoutePath}/routes (GET)`);
+    stateInstance.options.authWhitelist.push(new RegExp(`^${docRoutePath}/routes/[^/]+$`));
+    logger.startup("路由", `${docRoutePath}/routes/:id (GET)`);
+    stateInstance.options.authWhitelist.push(`${docRoutePath}/sync`);
+    logger.startup("路由", `${docRoutePath}/sync (POST)`);
+  }
+
+  return app;
+}

package/core/module/CreateModule.ts

@@ -0,0 +1,38 @@
+import { findPackageRoot } from "./FindPackageRoot";
+import { getModulePath } from "./GetModulePath";
+import { MindBaseApp } from "../../types";
+import logger from "../../utils/Logger";
+
+export interface LightUpModule {
+  install(app: MindBaseApp): Promise<void>;
+  __modulePath: string;
+}
+
+/**
+ * 创建一个 LightUp 模块
+ * @param install 模块安装函数
+ * @param callerPath 调用者的文件路径（通常是 __filename），如果不提供则尝试通过调用栈获取
+ * @returns LightUp 模块实例
+ * @throws 如果模块创建失败
+ */
+export function createModule(install, callerPath?: string): LightUpModule {
+  if (typeof install !== "function") {
+    throw new Error("模块安装函数必须是一个函数");
+  }
+
+  try {
+    // 优先使用传入的 callerPath，否则通过调用栈获取
+    const modulePath = callerPath || getModulePath();
+    const packageRoot = findPackageRoot(modulePath);
+
+    logger.debug(`创建模块：路径=${modulePath}，包根目录=${packageRoot}`);
+
+    return {
+      install,
+      __modulePath: packageRoot,
+    };
+  } catch (error) {
+    logger.error("模块创建失败：", error);
+    throw new Error(`模块创建失败：${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/core/module/FindPackageRoot.ts

@@ -0,0 +1,58 @@
+import path from "path";
+import fs from "fs";
+
+/**
+ * 查找包含 package.json 的根目录
+ * @param startPath 开始查找的路径
+ * @returns 包含 package.json 的目录路径
+ * @throws 如果输入路径无效
+ */
+export function findPackageRoot(startPath: string): string {
+  // 验证输入路径
+  if (!startPath || typeof startPath !== "string") {
+    throw new Error("无效的起始路径：路径必须是非空字符串");
+  }
+
+  // 确保路径是绝对路径
+  let currentPath: string;
+  try {
+    currentPath = path.isAbsolute(startPath) ? startPath : path.resolve(startPath);
+  } catch (e) {
+    throw new Error(`无法解析路径：${startPath}`);
+  }
+
+  // 验证路径是否存在
+  try {
+    if (!fs.existsSync(currentPath)) {
+      throw new Error(`路径不存在：${currentPath}`);
+    }
+
+    // 如果是文件，从其父目录开始查找
+    const stat = fs.statSync(currentPath);
+    if (stat.isFile()) {
+      currentPath = path.dirname(currentPath);
+    }
+  } catch (e) {
+    throw new Error(`路径验证失败：${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  // 向上查找 package.json
+  while (currentPath !== path.parse(currentPath).root) {
+    try {
+      const pkgJsonPath = path.join(currentPath, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        // 验证找到的 package.json 是否是文件
+        const pkgStat = fs.statSync(pkgJsonPath);
+        if (pkgStat.isFile()) {
+          return currentPath;
+        }
+      }
+    } catch (e) {
+      // 忽略单个路径的访问错误，继续向上查找
+    }
+    currentPath = path.dirname(currentPath);
+  }
+
+  // 如果没有找到 package.json，返回起始路径的父目录
+  return path.dirname(startPath);
+}

package/core/module/GetModulePath.ts

@@ -0,0 +1,58 @@
+import * as path from "path";
+
+/**
+ * 获取当前模块的路径
+ * @returns 当前模块的绝对路径
+ * @throws 如果无法确定模块路径
+ */
+export function getModulePath(): string {
+  // 从调用栈中提取调用者的路径
+  try {
+    const error = new Error();
+    if (error.stack) {
+      console.log("DEBUG STACK:", error.stack);
+      const stackLines = error.stack.split("\n");
+
+      // 跳过内部调用，找到真正的调用者
+      // 需要跳过：getModulePath, createModule, ts-node, node:internal
+      for (const line of stackLines) {
+        // 跳过内部函数和 Node.js/ts-node 的调用
+        if (!line.includes("at") ||
+            line.includes("getModulePath") ||
+            line.includes("createModule") ||
+            line.includes("CreateModule.ts") ||
+            line.includes("ts-node") ||
+            line.includes("node:internal")) {
+          continue;
+        }
+
+        // 提取文件路径
+        // 格式可能是：at xxx (/path/to/file.ts:1:2) 或 at /path/to/file.ts:1:2
+        const match = line.match(/\(([^:]+\.ts)/) || line.match(/at\s+([^:]+\.ts)/);
+        if (match && match[1]) {
+          const filePath = match[1];
+          console.log("提取到的路径:", filePath);
+          return path.resolve(filePath);
+        }
+      }
+    }
+  } catch (e) {
+    // 忽略提取 stack 时的错误
+  }
+
+  throw new Error("无法确定模块路径：当前环境不支持 __filename 且无法从调用栈中提取路径");
+}
+
+/**
+ * 获取当前模块所在的目录
+ * @returns 当前模块的目录路径
+ * @throws 如果无法确定模块路径
+ */
+export function getModuleDir(): string {
+  try {
+    const modulePath = getModulePath();
+    return path.dirname(modulePath);
+  } catch (error) {
+    throw new Error(`无法获取模块目录：${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/core/state.ts

@@ -0,0 +1,67 @@
+import express, { Express } from "express";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import { LogLevel } from "../types";
+
+export interface MindBaseAppOptions {
+  /** 服务监听主机名 @default 127.0.0.1 */
+  host?: string;
+  /** 服务监听端口 @default 3000 */
+  port?: number;
+  /** 是否启用请求日志 @default true */
+  logging?: boolean;
+  /** 静态文件目录路径 */
+  staticPath?: string;
+  /** 是否解析 User-Agent 信息 @default true */
+  userAgent?: boolean;
+  /** 是否解析 IP 地理位置信息 @default true */
+  ip?: boolean;
+  /** 是否启用 CORS 跨域 @default true */
+  cors?: boolean;
+  /** API 路由前缀，如 "/api" */
+  apiPrefix?: string;
+  /**
+   * 日志级别（优先级从低到高）:
+   * - debug: 调试信息（显示所有）
+   * - info: 普通信息（隐藏 debug）
+   * - warn: 警告信息（隐藏 debug、info）
+   * - error: 错误信息（隐藏 debug、info、warn）
+   * - silent: 静默模式（隐藏所有）
+   * @default "info"
+   */
+  logLevel?: LogLevel;
+  /** 数据库配置 */
+  database?: {
+    /** SQLite 数据库文件路径 @default "./data/app.db" */
+    path?: string;
+  };
+  /** 认证白名单路径（支持字符串和正则表达式） */
+  authWhitelist?: (string | RegExp)[];
+}
+export interface AppState {
+  options: MindBaseAppOptions;
+  express: Express;
+  db?: BetterSQLite3Database<Record<string, any>>; // Drizzle 数据库实例
+  schemas?: Record<string, any>; // 合并后的所有 schema
+}
+
+export function createState(options: MindBaseAppOptions = {}): AppState {
+  return {
+    options: {
+      host: options.host || "127.0.0.1",
+      port: options.port || 3000,
+      logging: options.logging !== false,
+      staticPath: options.staticPath,
+      userAgent: options.userAgent !== false,
+      ip: options.ip !== false,
+      cors: options.cors !== false,
+      apiPrefix: options.apiPrefix,
+      logLevel: options.logLevel || "info",
+      authWhitelist: [],
+      database: {
+        path: options.database?.path || "./data/app.db",
+      },
+    },
+    express: express(),
+    schemas: {},
+  };
+}

package/feature/cron/CronManager.ts

@@ -0,0 +1,63 @@
+import { CronJob } from "cron";
+import { randomUUID } from "crypto";
+
+interface CronConfig {
+  timezone?: string;
+}
+
+interface CronJobMap {
+  [id: string]: CronJob;
+}
+
+let jobs: CronJobMap = {};
+let config: CronConfig = {
+  timezone: "Asia/Shanghai",
+};
+
+export function setConfig(newConfig: CronConfig): void {
+  config = {
+    ...config,
+    ...newConfig,
+  };
+}
+
+export function addCron(pattern: string, handler: () => void | Promise<void>, customId?: string): string {
+  const id = customId || generateId();
+  if (jobs[id]) {
+    jobs[id].stop();
+  }
+  const job = new CronJob(pattern, handler, null, true, config.timezone);
+  jobs[id] = job;
+  return id;
+}
+
+export function stopCron(id: string): boolean {
+  const job = jobs[id];
+  if (job) {
+    job.stop();
+    delete jobs[id];
+    return true;
+  }
+  return false;
+}
+
+export function stopAllCron(): void {
+  Object.values(jobs).forEach((job) => {
+    job.stop();
+  });
+  jobs = {};
+}
+
+function generateId(): string {
+  return randomUUID();
+}
+
+const CronManager = {
+  setConfig,
+  addCron,
+  stopCron,
+  stopAllCron,
+};
+
+export default CronManager;
+export type { CronConfig };