openlearn-next 0.3.6 → 0.3.8

package/cli-cleaner.mjs

@@ -0,0 +1,131 @@
+import { existsSync, readdirSync, rmSync, unlinkSync, statSync, readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import os from 'node:os';
+
+/**
+ * 安全清理 openlearn-next 在本地的各类运行与包缓存
+ *
+ * @param {Object} options
+ * @param {boolean} [options.all]   是否全量清理（NPX 缓存 + 运行缓存 + 重置数据库）
+ * @param {boolean} [options.npx]   是否仅清理 NPX 缓存
+ * @param {boolean} [options.db]    是否仅清理/重置本地数据库
+ * @param {string}  [options.customDataDir] 自定义数据目录（可选，主要供测试用）
+ * @param {string}  [options.customNpxDir]  自定义 NPX 缓存目录（可选，主要供测试用）
+ * @param {boolean} [options.silent] 是否静默输出
+ * @returns {{ npxCleaned: number, dbReset: boolean, tempCleaned: string[] }}
+ */
+export function runClean(options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const results = {
+    npxCleaned: 0,
+    dbReset: false,
+    tempCleaned: [],
+  };
+
+  const isAll = Boolean(options.all);
+  const isOnlyNpx = Boolean(options.npx) && !isAll;
+  const isOnlyDb = Boolean(options.db) && !isAll;
+  const isDefault = !isOnlyNpx && !isOnlyDb && !isAll;
+
+  // ── 1. 清理 NPX 历史包缓存 ─────────────────────────────────────────────
+  if (isAll || isOnlyNpx || isDefault) {
+    const npxDir = options.customNpxDir ? resolve(options.customNpxDir) : join(os.homedir(), '.npm', '_npx');
+    if (existsSync(npxDir)) {
+      try {
+        const entries = readdirSync(npxDir);
+        for (const entry of entries) {
+          const entryPath = join(npxDir, entry);
+          try {
+            if (statSync(entryPath).isDirectory()) {
+              const targetPackage = join(entryPath, 'node_modules', 'openlearn-next');
+              if (existsSync(targetPackage)) {
+                let ver = 'unknown';
+                try {
+                  const pkgData = JSON.parse(readFileSync(join(targetPackage, 'package.json'), 'utf-8'));
+                  ver = pkgData.version || 'unknown';
+                } catch {
+                  // ignore JSON parse error
+                }
+                rmSync(entryPath, { recursive: true, force: true });
+                results.npxCleaned++;
+                log(`✓ 已清理 NPX 旧版缓存: ~/.npm/_npx/${entry} (openlearn-next@${ver})`);
+              }
+            }
+          } catch (err) {
+            // 单个目录清理失败不阻断整体流程
+          }
+        }
+      } catch (err) {
+        log(`⚠ 读取 NPX 缓存目录失败: ${err.message}`);
+      }
+    }
+    if (results.npxCleaned === 0 && !options.silent) {
+      log(`ℹ 未发现残留的 openlearn-next NPX 包缓存。`);
+    }
+  }
+
+  // ── 2. 清理本地运行与数据库缓存 ─────────────────────────────────────────
+  if (isAll || isOnlyDb || isDefault) {
+    const dataDir = options.customDataDir
+      ? resolve(options.customDataDir)
+      : (process.env.OPENLEARN_DB_PATH
+          ? dirname(resolve(process.env.OPENLEARN_DB_PATH))
+          : join(os.homedir(), 'openlearn-next'));
+
+    const dbPath = process.env.OPENLEARN_DB_PATH
+      ? resolve(process.env.OPENLEARN_DB_PATH)
+      : join(dataDir, 'data.db');
+
+    const walPath = `${dbPath}-wal`;
+    const shmPath = `${dbPath}-shm`;
+
+    if (existsSync(dataDir)) {
+      // (a) 数据库重置模式
+      if (isAll || isOnlyDb) {
+        if (existsSync(dbPath)) {
+          unlinkSync(dbPath);
+          results.dbReset = true;
+          log(`✓ 已重置本地数据库: ${dbPath}`);
+        }
+        if (existsSync(walPath)) {
+          unlinkSync(walPath);
+          log(`✓ 已清理 SQLite 预写日志: ${walPath}`);
+        }
+        if (existsSync(shmPath)) {
+          unlinkSync(shmPath);
+          log(`✓ 已清理 SQLite 共享内存: ${shmPath}`);
+        }
+        log(`ℹ 数据库已重置，下次启动将全新自动初始化。`);
+      } else {
+        // (b) 默认安全清理：清理 WAL 与临时运行日志，保留主库数据
+        if (existsSync(walPath)) {
+          unlinkSync(walPath);
+          results.tempCleaned.push(walPath);
+          log(`✓ 已清理 SQLite 临时预写日志: ${walPath}`);
+        }
+        if (existsSync(shmPath)) {
+          unlinkSync(shmPath);
+          results.tempCleaned.push(shmPath);
+          log(`✓ 已清理 SQLite 临时共享内存: ${shmPath}`);
+        }
+        if (!options.silent) {
+          log(`ℹ 本地数据库核心数据已保留 (${dbPath})。如需完全重置数据库，请添加 --db 或 --all 参数。`);
+        }
+      }
+
+      // (c) 清理临时子目录
+      const tempFolders = ['temp', 'scratch', 'cache'];
+      for (const folder of tempFolders) {
+        const folderPath = join(dataDir, folder);
+        if (existsSync(folderPath)) {
+          rmSync(folderPath, { recursive: true, force: true });
+          results.tempCleaned.push(folderPath);
+          log(`✓ 已清理临时数据目录: ${folderPath}`);
+        }
+      }
+    }
+  }
+
+  log(`缓存清理完成。`);
+  return results;
+}

package/cli-data.mjs

@@ -0,0 +1,252 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * 解析本地目标数据库路径
+ * @param {string} [customPath]
+ * @returns {string}
+ */
+export function resolveDbPath(customPath) {
+  if (customPath) return path.resolve(customPath);
+  if (process.env.OPENLEARN_DB_PATH) return path.resolve(process.env.OPENLEARN_DB_PATH);
+  return path.join(os.homedir(), 'openlearn-next', 'data.db');
+}
+
+/**
+ * 一键数据冷备
+ * @param {string} [outputFile]
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, targetFile?: string, error?: string }>}
+ */
+export async function runBackup(outputFile, options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    const msg = `数据库文件未找到: ${dbPath}`;
+    log(`✗ 备份失败: ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  const timestamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const target = outputFile
+    ? path.resolve(outputFile)
+    : path.resolve(process.cwd(), `openlearn_backup_${timestamp}.db`);
+
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath, { readonly: true });
+    await db.backup(target);
+    db.close();
+
+    const stat = fs.statSync(target);
+    const sizeKb = Math.round(stat.size / 1024);
+    log(`✓ 数据库冷备完成！`);
+    log(`  快照文件: ${target} (${sizeKb} KB)`);
+    return { ok: true, targetFile: target };
+  } catch (err) {
+    // 降级为物理文件复制
+    try {
+      fs.copyFileSync(dbPath, target);
+      const stat = fs.statSync(target);
+      const sizeKb = Math.round(stat.size / 1024);
+      log(`✓ 数据库文件冷备完成（直接镜像模式）：${target} (${sizeKb} KB)`);
+      return { ok: true, targetFile: target };
+    } catch (copyErr) {
+      log(`✗ 备份写入失败: ${copyErr.message}`);
+      return { ok: false, error: copyErr.message };
+    }
+  }
+}
+
+/**
+ * 数据安全回滚与还原
+ * @param {string} sourceFile
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function runRestore(sourceFile, options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  if (!sourceFile) {
+    const msg = '未指定待还原的备份文件。用法: npx openlearn-next restore <backup.db>';
+    log(`✗ ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  const src = path.resolve(sourceFile);
+  if (!fs.existsSync(src)) {
+    const msg = `指定的备份文件不存在: ${src}`;
+    log(`✗ ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  // 校验 SQLite 文件头 (Magic Header: "SQLite format 3\0")
+  try {
+    const fd = fs.openSync(src, 'r');
+    const buffer = Buffer.alloc(16);
+    fs.readSync(fd, buffer, 0, 16, 0);
+    fs.closeSync(fd);
+    const headerStr = buffer.toString('utf-8');
+    if (!headerStr.startsWith('SQLite format 3')) {
+      const msg = `文件并非有效的 SQLite 数据库备份: ${src}`;
+      log(`✗ ${msg}`);
+      return { ok: false, error: msg };
+    }
+  } catch (err) {
+    log(`✗ 读取备份文件头失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+
+  const dbPath = resolveDbPath(options.dbPath);
+  const dbDir = path.dirname(dbPath);
+  fs.mkdirSync(dbDir, { recursive: true });
+
+  // 创建自动回滚副本
+  if (fs.existsSync(dbPath)) {
+    const bakFile = `${dbPath}.bak_${Date.now()}`;
+    fs.copyFileSync(dbPath, bakFile);
+    log(`ℹ 已为现有数据库创建安全回滚镜像: ${bakFile}`);
+  }
+
+  try {
+    fs.copyFileSync(src, dbPath);
+    // 清理旧的 WAL 与 SHM
+    const wal = `${dbPath}-wal`;
+    const shm = `${dbPath}-shm`;
+    if (fs.existsSync(wal)) fs.unlinkSync(wal);
+    if (fs.existsSync(shm)) fs.unlinkSync(shm);
+
+    log(`✓ 数据库还原成功！当前主库已切换为 ${src} 的数据。`);
+    return { ok: true };
+  } catch (err) {
+    log(`✗ 覆盖写入数据库失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * 命令行一键重置管理员 (admin) 密码
+ * @param {string} [newPassword='admin']
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function runResetAdmin(newPassword = 'admin', options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    const msg = `数据库尚未初始化 (${dbPath})。请直接启动一次平台即可生成默认 admin/admin 账号。`;
+    log(`ℹ ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  try {
+    let hash;
+    try {
+      const bcrypt = (await import('bcryptjs')).default;
+      hash = bcrypt.hashSync(newPassword, 10);
+    } catch {
+      const crypto = await import('node:crypto');
+      hash = crypto.createHash('sha256').update(newPassword).digest('hex');
+    }
+
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath);
+
+    const updateRes = db.prepare('UPDATE users SET password_hash = ? WHERE username = ?').run(hash, 'admin');
+
+    if (updateRes.changes === 0) {
+      // 若数据库中无 admin 用户，则插入
+      db.prepare('INSERT INTO users (id, username, password_hash, role, name, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(`usr_admin_${Date.now()}`, 'admin', hash, 'administrator', 'System Admin', Date.now());
+      log(`✓ 管理员账号不存在，已新建管理员账号: admin (密码: ${newPassword})`);
+    } else {
+      log(`✓ 管理员 (admin) 密码已成功重置为: ${newPassword}`);
+    }
+
+    db.close();
+    return { ok: true };
+  } catch (err) {
+    log(`✗ 重置密码失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * 命令行插件状态速查
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, plugins?: Array<any>, error?: string }>}
+ */
+export async function runPluginsList(options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    log(`数据库文件尚未创建 (${dbPath})，暂无插件安装记录。`);
+    return { ok: true, plugins: [] };
+  }
+
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath, { readonly: true });
+
+    // 检查 plugins 表是否存在
+    const tableCheck = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='plugins'").get();
+    if (!tableCheck) {
+      log(`未检测到 plugins 数据表，平台尚未加载插件体系。`);
+      db.close();
+      return { ok: true, plugins: [] };
+    }
+
+    const rows = db.prepare('SELECT * FROM plugins ORDER BY id ASC').all();
+    db.close();
+
+    const plugins = rows.map((p) => {
+      let version = '1.0.0';
+      if (p.manifest) {
+        try {
+          const parsed = JSON.parse(p.manifest);
+          if (parsed.version) version = parsed.version;
+        } catch {}
+      }
+      return {
+        id: p.id,
+        name: p.name,
+        version,
+        status: p.status,
+        loader_version: p.loader_version || p.execution_mode || 'inline',
+      };
+    });
+
+    if (!options.silent) {
+      const bold = '\x1b[1m';
+      const green = '\x1b[32m';
+      const yellow = '\x1b[33m';
+      const cyan = '\x1b[36m';
+      const reset = '\x1b[0m';
+
+      console.log(`\n${bold}${cyan}已安装插件清单 (${plugins.length} 个):${reset}`);
+      console.log(`┌──────────────────────────────────────────────┬─────────┬──────────┬──────────┐`);
+      console.log(`│ ${bold}Plugin ID${reset}${' '.repeat(37)}│ ${bold}Version${reset} │ ${bold}Status${reset}   │ ${bold}Mode${reset}     │`);
+      console.log(`├──────────────────────────────────────────────┼─────────┼──────────┼──────────┤`);
+
+      for (const p of plugins) {
+        const idCol = p.id.padEnd(44);
+        const verCol = (p.version || '1.0.0').padEnd(7);
+        const statusColor = p.status === 'active' ? green : yellow;
+        const statusCol = `${statusColor}${p.status.padEnd(8)}${reset}`;
+        const modeCol = (p.loader_version || 'inline').padEnd(8);
+        console.log(`│ ${idCol} │ ${verCol} │ ${statusCol} │ ${modeCol} │`);
+      }
+      console.log(`└──────────────────────────────────────────────┴─────────┴──────────┴──────────┘\n`);
+    }
+
+    return { ok: true, plugins };
+  } catch (err) {
+    log(`✗ 查询插件失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}

package/cli-doctor.mjs

@@ -0,0 +1,189 @@
+import os from 'node:os';
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 诊断指定端口是否可用
+ * @param {number} port
+ * @param {string} host
+ * @returns {Promise<boolean>}
+ */
+export function checkPortAvailable(port, host = '0.0.0.0') {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        resolve(false);
+      }
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}
+
+/**
+ * 获取本机所有局域网可用 IPv4 地址
+ * @returns {string[]}
+ */
+export function getNetworkIps() {
+  const ips = [];
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name] || []) {
+      if (iface.family === 'IPv4' && !iface.internal && !iface.address.startsWith('127.')) {
+        ips.push(iface.address);
+      }
+    }
+  }
+  return ips;
+}
+
+/**
+ * 运行系统环境自检与健康诊断
+ * @param {Object} [options]
+ * @param {number} [options.port]
+ * @param {string} [options.dbPath]
+ * @param {boolean} [options.silent]
+ * @returns {Promise<{ ok: boolean, checks: Array<{ name: string, status: 'ok'|'warn'|'err', message: string }> }>}
+ */
+export async function runDoctor(options = {}) {
+  const checks = [];
+  const silent = Boolean(options.silent);
+
+  // 1. Node.js 版本检查 (>= 20.0.0)
+  const nodeVersion = process.versions.node;
+  const majorNodeVersion = parseInt(nodeVersion.split('.')[0], 10);
+  if (majorNodeVersion >= 20) {
+    checks.push({
+      name: 'Node.js Runtime',
+      status: 'ok',
+      message: `v${nodeVersion} (满足 >= 20.0.0 要求)`,
+    });
+  } else {
+    checks.push({
+      name: 'Node.js Runtime',
+      status: 'err',
+      message: `v${nodeVersion} 过低！OpenLearn 核心需要 Node.js >= 20.0.0，请升级。`,
+    });
+  }
+
+  // 2. 操作系统与硬件
+  const cpus = os.cpus() || [];
+  const totalMemGb = Math.round((os.totalmem() / 1024 / 1024 / 1024) * 10) / 10;
+  const freeMemMb = Math.round(os.freemem() / 1024 / 1024);
+  checks.push({
+    name: 'Hardware & OS',
+    status: 'ok',
+    message: `${process.platform} (${process.arch}, ${cpus.length} CPU 核心, ${totalMemGb} GB 内存)`,
+  });
+
+  if (freeMemMb < 256) {
+    checks.push({
+      name: 'Memory Headroom',
+      status: 'warn',
+      message: `剩余可用内存偏低 (${freeMemMb} MB)，可能影响大课件解析`,
+    });
+  } else {
+    checks.push({
+      name: 'Memory Headroom',
+      status: 'ok',
+      message: `充足 (当前剩余 ${freeMemMb} MB 可用)`,
+    });
+  }
+
+  // 3. 数据库目录与读写权限
+  const dbPath = options.dbPath
+    ? path.resolve(options.dbPath)
+    : (process.env.OPENLEARN_DB_PATH
+        ? path.resolve(process.env.OPENLEARN_DB_PATH)
+        : path.join(os.homedir(), 'openlearn-next', 'data.db'));
+  const dbDir = path.dirname(dbPath);
+
+  try {
+    fs.mkdirSync(dbDir, { recursive: true });
+    // 测试临时写入
+    const testFile = path.join(dbDir, `.doctor_write_test_${Date.now()}`);
+    fs.writeFileSync(testFile, 'test');
+    fs.unlinkSync(testFile);
+    checks.push({
+      name: 'Database Storage',
+      status: 'ok',
+      message: `${dbPath} (目录正常且具备读写权限)`,
+    });
+  } catch (err) {
+    checks.push({
+      name: 'Database Storage',
+      status: 'err',
+      message: `目录 ${dbDir} 写入失败: ${err.message}`,
+    });
+  }
+
+  // 4. 端口可用性检查
+  const targetPort = options.port || parseInt(process.env.PORT || '9000', 10);
+  const isPortAvailable = await checkPortAvailable(targetPort);
+  if (isPortAvailable) {
+    checks.push({
+      name: `Port ${targetPort}`,
+      status: 'ok',
+      message: `可用 (未被其他进程占用)`,
+    });
+  } else {
+    checks.push({
+      name: `Port ${targetPort}`,
+      status: 'warn',
+      message: `已被占用！启动时会自动重试或可通过 -p <other_port> 更换端口`,
+    });
+  }
+
+  // 5. 局域网接入点
+  const netIps = getNetworkIps();
+  if (netIps.length > 0) {
+    checks.push({
+      name: 'Network Access',
+      status: 'ok',
+      message: `检测到局域网 IP: ${netIps.join(', ')}`,
+    });
+  } else {
+    checks.push({
+      name: 'Network Access',
+      status: 'warn',
+      message: `未检测到外部局域网 IPv4 地址（仅可通过 localhost 本机访问）`,
+    });
+  }
+
+  const allOk = checks.every((c) => c.status !== 'err');
+
+  if (!silent) {
+    const bold = '\x1b[1m';
+    const green = '\x1b[32m';
+    const yellow = '\x1b[33m';
+    const red = '\x1b[31m';
+    const cyan = '\x1b[36m';
+    const reset = '\x1b[0m';
+
+    console.log(`\n${bold}${cyan}╔═════════════════════════════════════════════════════════════╗${reset}`);
+    console.log(`${bold}${cyan}║           OpenLearn V2 System Diagnostics (doctor)          ║${reset}`);
+    console.log(`${bold}${cyan}╚═════════════════════════════════════════════════════════════╝${reset}\n`);
+
+    for (const c of checks) {
+      let icon = `${green}✓${reset}`;
+      if (c.status === 'warn') icon = `${yellow}⚠${reset}`;
+      if (c.status === 'err') icon = `${red}✗${reset}`;
+      console.log(`  ${icon} ${bold}${c.name.padEnd(18)}${reset} : ${c.message}`);
+    }
+
+    console.log(`\n${cyan}───────────────────────────────────────────────────────────────${reset}`);
+    if (allOk) {
+      console.log(`  ${bold}${green}诊断通过！核心运行环境健康，已具备课堂部署就绪状态。${reset}\n`);
+    } else {
+      console.log(`  ${bold}${red}诊断发现阻断性问题，请根据上述提示处理后重试。${reset}\n`);
+    }
+  }
+
+  return { ok: allOk, checks };
+}