@code2rich/jpage 1.5.0

package/test/perf-harness.js

@@ -0,0 +1,198 @@
+// 端到端验证套件：覆盖鉴权、上传、列表、渲染、搜索、短链、版本、MCP、缓存头
+// 用法: node test/perf-harness.js [PORT]
+// 退出码 0 = 全部通过, 非 0 = 有失败
+const http = require('http');
+const crypto = require('crypto');
+
+const PORT = parseInt(process.argv[2] || process.env.PORT || '8890', 10);
+const HOST = '127.0.0.1';
+const ADMIN = 'admin';
+const PASS = 'testpassword123';
+
+let pass = 0, fail = 0;
+const failures = [];
+
+function check(name, cond, detail) {
+  if (cond) { pass++; console.log(`  ✓ ${name}`); }
+  else { fail++; failures.push(`${name}${detail ? ' :: ' + detail : ''}`); console.log(`  ✗ ${name}${detail ? ' :: ' + detail : ''}`); }
+}
+
+function req(method, path, { body, headers = {}, raw, formData } = {}) {
+  return new Promise((resolve, reject) => {
+    const opts = { host: HOST, port: PORT, method, path, headers: { ...headers } };
+    let payload = null;
+    if (raw !== undefined) { payload = raw; if (!opts.headers['Content-Type']) opts.headers['Content-Type'] = 'application/json'; }
+    else if (body !== undefined) { payload = JSON.stringify(body); opts.headers['Content-Type'] = 'application/json'; }
+    else if (formData !== undefined) { payload = formData.body; Object.assign(opts.headers, formData.headers); }
+    if (payload) opts.headers['Content-Length'] = Buffer.byteLength(payload);
+    const r = http.request(opts, res => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => {
+        const buf = Buffer.concat(chunks);
+        resolve({ status: res.statusCode, headers: res.headers, buf, text: buf.toString('utf8') });
+      });
+    });
+    r.on('error', reject);
+    if (payload) r.write(payload);
+    r.end();
+  });
+}
+
+// 多部分表单：单字段 file
+function multipart(boundary, field) {
+  const CRLF = '\r\n';
+  const pre = `--${boundary}${CRLF}Content-Disposition: form-data; name="file"; filename="${field.filename}"${CRLF}Content-Type: ${field.type || 'text/markdown'}${CRLF}${CRLF}`;
+  const post = `${CRLF}--${boundary}--${CRLF}`;
+  const body = Buffer.concat([Buffer.from(pre, 'utf8'), Buffer.from(field.content, 'utf8'), Buffer.from(post, 'utf8')]);
+  return { body, headers: { 'Content-Type': `multipart/form-data; boundary=${boundary}` } };
+}
+
+async function run() {
+  console.log(`\n=== jpage 验证套件 (port ${PORT}) ===\n`);
+
+  // 1. 健康检查
+  let r = await req('GET', '/health');
+  check('GET /health 200', r.status === 200, `status=${r.status}`);
+  check('health 报告 db ok', (() => { try { return JSON.parse(r.text).db === true; } catch { return false; } })());
+
+  // 2. 未登录访问受保护端点 → 401
+  r = await req('GET', '/api/auth/me');
+  check('未登录 GET /api/auth/me → 401', r.status === 401, `status=${r.status}`);
+
+  // 3. 登录
+  r = await req('POST', '/api/auth/login', { body: { username: ADMIN, password: PASS } });
+  check('登录 admin → 200', r.status === 200, `status=${r.status}`);
+  const cookie = (r.headers['set-cookie'] || []).map(c => c.split(';')[0]).join('; ');
+  check('登录返回 cookie', !!cookie);
+  const auth = { Cookie: cookie };
+  let me;
+  try { me = JSON.parse(r.text); } catch { me = {}; }
+  check('登录响应含 id/username/role', !!me.id && !!me.username && me.role === 'admin', JSON.stringify(me));
+
+  // 4. /api/auth/me
+  r = await req('GET', '/api/auth/me', { headers: auth });
+  check('GET /api/auth/me → 200 (带 cookie)', r.status === 200, `status=${r.status}`);
+
+  // 5. 上传 Markdown (JSON)
+  const mdContent = '# 标题\n\n```js\nconsole.log("hi");\n```\n\n行内公式 $a^2+b^2=c^2$\n\n搜索关键词 jpage_unique_token_alpha';
+  r = await req('POST', '/api/files/upload-json', { headers: auth, body: { name: 'perf-test.md', content: mdContent, isPublic: true } });
+  check('upload-json markdown → 200', r.status === 200, `status=${r.status} ${r.text}`);
+  let upload = {};
+  try { upload = JSON.parse(r.text); } catch {}
+  check('上传返回 id + share_key', !!upload.id && !!upload.share_key, r.text);
+  const fileId = upload.id;
+  const shareKey = upload.share_key;
+
+  // 6. 列表
+  r = await req('GET', '/api/files', { headers: auth });
+  check('GET /api/files → 200', r.status === 200, `status=${r.status}`);
+  let list = {};
+  try { list = JSON.parse(r.text); } catch {}
+  check('列表含刚上传文件', Array.isArray(list.files) && list.files.some(f => f.id === fileId), r.text.slice(0, 200));
+  check('列表文件含 tags 数组', list.files.some(f => Array.isArray(f.tags)), '');
+  check('列表含 pagination', !!list.pagination, '');
+
+  // 7. 文件详情
+  r = await req('GET', `/api/files/${fileId}`, { headers: auth });
+  check(`GET /api/files/${fileId} → 200`, r.status === 200, `status=${r.status}`);
+
+  // 8. 内容
+  r = await req('GET', `/api/files/${fileId}/content`, { headers: auth });
+  check(`GET /api/files/${fileId}/content → 200`, r.status === 200, `status=${r.status}`);
+
+  // 9. 渲染
+  r = await req('GET', `/api/files/${fileId}/render`, { headers: auth });
+  check(`render → 200`, r.status === 200, `status=${r.status}`);
+  check('render 返回 html 且含高亮/katex', r.text.includes('<code') || r.text.includes('katex'), r.text.slice(0, 120));
+
+  // 10. 搜索（FTS）
+  await new Promise(res => setTimeout(res, 400)); // 等 FTS 异步索引
+  r = await req('GET', `/api/files/search?q=${encodeURIComponent('jpage_unique_token_alpha')}`, { headers: auth });
+  check('FTS 搜索 → 200', r.status === 200, `status=${r.status}`);
+  let search = {};
+  try { search = JSON.parse(r.text); } catch {}
+  check('FTS 搜索命中目标文件', Array.isArray(search.files) && search.files.some(f => f.id === fileId), r.text.slice(0, 200));
+
+  // 11. 覆盖上传（版本）
+  r = await req('POST', `/api/files/${fileId}/overwrite-json`, { headers: auth, body: { content: '# v2\n\n更新内容' } });
+  check('overwrite-json → 200', r.status === 200, `status=${r.status} ${r.text}`);
+  r = await req('GET', `/api/files/${fileId}/versions`, { headers: auth });
+  check('版本列表 → 200', r.status === 200, `status=${r.status}`);
+
+  // 12. 短链 /s/:key
+  r = await req('GET', `/s/${shareKey}`);
+  check(`短链 /s/${shareKey} → 200`, r.status === 200, `status=${r.status}`);
+  check('短链渲染含 html', r.text.includes('<html') || r.text.includes('<!DOCTYPE'), r.text.slice(0, 80));
+
+  // 13. 标签 / 分类（含分类名称缓存验证）
+  r = await req('POST', '/api/tags', { headers: auth, body: { name: 'perf-tag' } });
+  check('创建标签 → 200/201', r.status === 200 || r.status === 201, `status=${r.status}`);
+  r = await req('PUT', `/api/files/${fileId}/tags`, { headers: auth, body: { tagIds: [1] } });
+  check('给文件打标签 → 200', r.status === 200, `status=${r.status}`);
+  r = await req('POST', '/api/categories', { headers: auth, body: { name: '缓存验证分类' } });
+  check('创建分类 → 200', r.status === 200, `status=${r.status}`);
+  let createdCat = {};
+  try { createdCat = JSON.parse(r.text); } catch {}
+  if (createdCat.id) {
+    r = await req('PUT', `/api/files/${fileId}/category`, { headers: auth, body: { categoryId: createdCat.id } });
+    check('给文件设置分类 → 200', r.status === 200, `status=${r.status}`);
+    // 列表应通过分类缓存返回正确的 category_name
+    r = await req('GET', '/api/files?keyword=perf-test.md', { headers: auth });
+    let withCat = {};
+    try { withCat = JSON.parse(r.text); } catch {}
+    const target = (withCat.files || []).find(f => f.id === fileId);
+    check('列表 category_name 由缓存正确填充', !!target && target.category_name === '缓存验证分类',
+      target ? `got category_name="${target.category_name}"` : 'file not found in list');
+    // 重命名后缓存应失效，列表反映新名
+    r = await req('PUT', `/api/categories/${createdCat.id}`, { headers: auth, body: { name: '重命名后的分类' } });
+    check('重命名分类 → 200', r.status === 200, `status=${r.status}`);
+    r = await req('GET', '/api/files?keyword=perf-test.md', { headers: auth });
+    let renamed = {};
+    try { renamed = JSON.parse(r.text); } catch {}
+    const target2 = (renamed.files || []).find(f => f.id === fileId);
+    check('分类重命名后列表反映新名称（缓存失效）', !!target2 && target2.category_name === '重命名后的分类',
+      target2 ? `got category_name="${target2.category_name}"` : 'file not found');
+  }
+  r = await req('GET', '/api/categories', { headers: auth });
+  check('GET /api/categories → 200', r.status === 200, `status=${r.status}`);
+
+  // 14. 静态资源缓存头（优化后应为长缓存）
+  r = await req('GET', '/css/style.css?v=1.5.0');
+  check('GET /css/style.css → 200', r.status === 200, `status=${r.status}`);
+  const cssCache = r.headers['cache-control'] || '';
+  console.log(`    (css cache-control: "${cssCache}")`);
+
+  // 15. 删除文件
+  r = await req('DELETE', `/api/files/${fileId}`, { headers: auth });
+  check('删除文件 → 200', r.status === 200, `status=${r.status}`);
+
+  // 16. 二次渲染（缓存路径，若启用）
+  // 重新上传一个用于短链热路径
+  r = await req('POST', '/api/files/upload-json', { headers: auth, body: { name: 'cache-target.md', content: '# C\n\n缓存验证', isPublic: true } });
+  let c2 = {};
+  try { c2 = JSON.parse(r.text); } catch {}
+  if (c2.id) {
+    const t1 = process.hrtime.bigint();
+    r = await req('GET', `/api/files/${c2.id}/render`, { headers: auth });
+    const t2 = process.hrtime.bigint();
+    const ms1 = Number(t2 - t1) / 1e6;
+    const t3 = process.hrtime.bigint();
+    r = await req('GET', `/api/files/${c2.id}/render`, { headers: auth });
+    const t4 = process.hrtime.bigint();
+    const ms2 = Number(t4 - t3) / 1e6;
+    console.log(`    (render cold=${ms1.toFixed(2)}ms, warm=${ms2.toFixed(2)}ms)`);
+    check('二次渲染同样成功', r.status === 200, `status=${r.status}`);
+    await req('DELETE', `/api/files/${c2.id}`, { headers: auth });
+  }
+
+  // 17. 不存在的资源 id → 404（非 500）
+  r = await req('GET', '/api/files/99999/render', { headers: auth });
+  check('render 不存在文件 → 404', r.status === 404, `status=${r.status}`);
+
+  console.log(`\n=== 结果: ${pass} 通过, ${fail} 失败 ===`);
+  if (fail > 0) { console.log('失败项:'); failures.forEach(f => console.log('  - ' + f)); process.exit(1); }
+  process.exit(0);
+}
+
+run().catch(e => { console.error('套件异常:', e); process.exit(2); });

package/test/run-server.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# 启动一个隔离的 jpage 实例用于测试
+# 用法: PORT=8891 bash test/run-server.sh &   (后台)
+#       bash test/run-server.sh                (前台)
+set -euo pipefail
+PORT="${PORT:-8890}"
+DATA_DIR="${JPAGE_DATA_DIR:-$(pwd)/data-test-$PORT}"
+export PORT NODE_ENV ADMIN_USER ADMIN_PASSWORD JPAGE_DATA_DIR MCP_TOKEN
+NODE_ENV="${NODE_ENV:-development}"
+ADMIN_USER="${ADMIN_USER:-admin}"
+ADMIN_PASSWORD="${ADMIN_PASSWORD:-testpassword123}"
+JPAGE_DATA_DIR="$DATA_DIR"
+MCP_TOKEN="${MCP_TOKEN:-test-mcp-token-abc}"
+mkdir -p "$DATA_DIR"
+exec node server.js

package/test/unit/cli-args.test.js

@@ -0,0 +1,88 @@
+// bin/args.js argv 解析器单元测试
+const test = require('node:test');
+const assert = require('node:assert');
+const { parse } = require('../../bin/args');
+
+test('parse: 空数组 → cmd/sub 为 null', () => {
+  const r = parse([]);
+  assert.strictEqual(r.cmd, null);
+  assert.strictEqual(r.sub, null);
+  assert.deepStrictEqual(r.opts, {});
+  assert.deepStrictEqual(r.positional, []);
+});
+
+test('parse: 单命令', () => {
+  const r = parse(['ls']);
+  assert.strictEqual(r.cmd, 'ls');
+  assert.strictEqual(r.sub, null);
+  assert.deepStrictEqual(r.positional, ['ls']);
+});
+
+test('parse: 命令 + 子命令', () => {
+  const r = parse(['skills', 'ls']);
+  assert.strictEqual(r.cmd, 'skills');
+  assert.strictEqual(r.sub, 'ls');
+  assert.deepStrictEqual(r.positional, ['skills', 'ls']);
+});
+
+test('parse: 命令 + 位置参数（3 个）', () => {
+  const r = parse(['mv', '12', 'new.html']);
+  assert.strictEqual(r.cmd, 'mv');
+  assert.strictEqual(r.sub, '12');
+  assert.deepStrictEqual(r.positional, ['mv', '12', 'new.html']);
+});
+
+test('parse: --key value 形式', () => {
+  const r = parse(['ls', '--page', '2', '--limit', '50']);
+  assert.strictEqual(r.opts.page, '2');
+  assert.strictEqual(r.opts.limit, '50');
+});
+
+test('parse: --key=value 形式', () => {
+  const r = parse(['ls', '--page=2', '--limit=50']);
+  assert.strictEqual(r.opts.page, '2');
+  assert.strictEqual(r.opts.limit, '50');
+});
+
+test('parse: 布尔标志（无值）', () => {
+  const r = parse(['upload', 'a.html', '--public']);
+  assert.strictEqual(r.opts.public, true);
+  assert.deepStrictEqual(r.positional, ['upload', 'a.html']);
+});
+
+test('parse: 布尔标志后跟另一个选项时识别为布尔', () => {
+  const r = parse(['upload', 'a.html', '--public', '--token', 'x']);
+  assert.strictEqual(r.opts.public, true);
+  assert.strictEqual(r.opts.token, 'x');
+});
+
+test('parse: -- 后内容全部当位置参数', () => {
+  const r = parse(['cat', '--', '--weird-id']);
+  assert.deepStrictEqual(r.positional, ['cat', '--weird-id']);
+  assert.strictEqual(r.opts['weird-id'], undefined);
+});
+
+test('parse: 选项在命令之前也能解析', () => {
+  const r = parse(['--token', 'abc', 'ls', '--page', '1']);
+  assert.strictEqual(r.opts.token, 'abc');
+  assert.strictEqual(r.cmd, 'ls');
+  assert.strictEqual(r.opts.page, '1');
+});
+
+test('parse: --token=value 与位置参数混合', () => {
+  const r = parse(['--token=abc', 'upload', 'x.html']);
+  assert.strictEqual(r.opts.token, 'abc');
+  assert.strictEqual(r.cmd, 'upload');
+  assert.strictEqual(r.sub, 'x.html');
+});
+
+test('parse: 末尾布尔标志（无后续 token）', () => {
+  const r = parse(['upload', 'x.html', '--public']);
+  assert.strictEqual(r.opts.public, true);
+});
+
+test('parse: 多个布尔标志', () => {
+  const r = parse(['x', '--public', '--verbose']);
+  assert.strictEqual(r.opts.public, true);
+  assert.strictEqual(r.opts.verbose, true);
+});

package/test/unit/cli-config.test.js

@@ -0,0 +1,89 @@
+// bin/config.js 配置解析单元测试
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { resolveConfig, parseEnvFile, loadEnvUp, DEFAULT_BASE } = require('../../bin/config');
+
+test('parseEnvFile: 基本 KEY=VALUE', () => {
+  const tmp = path.join(os.tmpdir(), '.env-test-' + process.pid);
+  fs.writeFileSync(tmp, 'MCP_TOKEN=abc123\nJPAGE_BASE=http://1.2.3.4:8858\n');
+  const parsed = parseEnvFile(tmp);
+  assert.strictEqual(parsed.MCP_TOKEN, 'abc123');
+  assert.strictEqual(parsed.JPAGE_BASE, 'http://1.2.3.4:8858');
+  fs.unlinkSync(tmp);
+});
+
+test('parseEnvFile: 去引号 + 跳过注释/空行', () => {
+  const tmp = path.join(os.tmpdir(), '.env-test2-' + process.pid);
+  fs.writeFileSync(tmp, '# 注释\nFOO="bar baz"\nQUOTED=\'single\'\n\n');
+  const parsed = parseEnvFile(tmp);
+  assert.strictEqual(parsed.FOO, 'bar baz');
+  assert.strictEqual(parsed.QUOTED, 'single');
+  fs.unlinkSync(tmp);
+});
+
+test('parseEnvFile: 不存在返回空对象', () => {
+  assert.deepStrictEqual(parseEnvFile('/no/such/path/.env'), {});
+});
+
+test('resolveConfig: --token 最高优先级', () => {
+  const r = resolveConfig({ token: 'cli' }, { JPAGE_TOKEN: 'env', MCP_TOKEN: 'global' });
+  assert.strictEqual(r.token, 'cli');
+});
+
+test('resolveConfig: JPAGE_TOKEN 高于 MCP_TOKEN', () => {
+  const r = resolveConfig({}, { JPAGE_TOKEN: 'jp', MCP_TOKEN: 'mc' });
+  assert.strictEqual(r.token, 'jp');
+});
+
+test('resolveConfig: 回退 MCP_TOKEN', () => {
+  const r = resolveConfig({}, { MCP_TOKEN: 'mc' });
+  assert.strictEqual(r.token, 'mc');
+});
+
+test('resolveConfig: 无 token 返回 null', () => {
+  // 用临时 cwd，避免读到项目根的 .env（其中有 MCP_TOKEN）造成泄漏
+  const cleanCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'jpage-clean-'));
+  try {
+    const r = resolveConfig({}, {}, cleanCwd);
+    assert.strictEqual(r.token, null);
+  } finally {
+    fs.rmSync(cleanCwd, { recursive: true, force: true });
+  }
+});
+
+test('resolveConfig: --base 优先于环境变量', () => {
+  const r = resolveConfig({ base: 'http://cli:9' }, { JPAGE_BASE: 'http://env:9' });
+  assert.strictEqual(r.base, 'http://cli:9');
+});
+
+test('resolveConfig: base 去尾部斜杠', () => {
+  const r = resolveConfig({ base: 'http://x:9///' }, {});
+  assert.strictEqual(r.base, 'http://x:9');
+});
+
+test('resolveConfig: 默认 base', () => {
+  assert.strictEqual(resolveConfig({}, {}).base, DEFAULT_BASE);
+});
+
+test('loadEnvUp: 向上查找 .env 并合并', () => {
+  // 在临时目录树里放 .env，验证向上查找
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'jpage-env-'));
+  const sub = path.join(root, 'a', 'b');
+  fs.mkdirSync(sub, { recursive: true });
+  fs.writeFileSync(path.join(root, '.env'), 'MCP_TOKEN=root-token\nJPAGE_BASE=http://root:9\n');
+  const loaded = loadEnvUp(sub);
+  assert.strictEqual(loaded.MCP_TOKEN, 'root-token');
+  assert.strictEqual(loaded.JPAGE_BASE, 'http://root:9');
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('resolveConfig: .env 里的 MCP_TOKEN 被用作回退', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'jpage-env2-'));
+  fs.writeFileSync(path.join(root, '.env'), 'MCP_TOKEN=from-file\n');
+  const r = resolveConfig({}, {}, root);
+  assert.strictEqual(r.token, 'from-file');
+  fs.rmSync(root, { recursive: true, force: true });
+});

package/test/unit/crypto.test.js

@@ -0,0 +1,100 @@
+// lib/crypto.js 单元测试：AES-256-GCM 加解密往返、密钥持久化、密钥变更后解密失败。
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// 用临时数据目录隔离密钥文件
+const TMP_DATA = path.join(__dirname, '..', `data-crypto-${process.pid}-${Date.now()}`);
+
+function freshCrypto() {
+  // 清除缓存，让 lib/crypto.js 重新读取 JPAGE_DATA_DIR / 环境变量
+  delete require.cache[require.resolve('../../lib/paths')];
+  delete require.cache[require.resolve('../../lib/crypto')];
+  return require('../../lib/crypto');
+}
+
+test.beforeEach(() => {
+  fs.rmSync(TMP_DATA, { recursive: true, force: true });
+  fs.mkdirSync(TMP_DATA, { recursive: true });
+  delete process.env.TOKEN_ENCRYPTION_KEY;
+  process.env.JPAGE_DATA_DIR = TMP_DATA;
+});
+
+test.afterEach(() => {
+  fs.rmSync(TMP_DATA, { recursive: true, force: true });
+  delete process.env.TOKEN_ENCRYPTION_KEY;
+});
+
+test('加密后解密能还原原文', () => {
+  const { encryptToken, decryptToken } = freshCrypto();
+  const plain = 'jp_abcdefghijklmnopqrstuvwxyz123456';
+  const enc = encryptToken(plain);
+  assert.notStrictEqual(enc, plain, '密文不应等于明文');
+  assert.strictEqual(decryptToken(enc), plain);
+});
+
+test('同一明文每次加密结果不同（随机 IV）', () => {
+  const { encryptToken } = freshCrypto();
+  const plain = 'jp_sametokenvalue';
+  const a = encryptToken(plain);
+  const b = encryptToken(plain);
+  assert.notStrictEqual(a, b, '不同次加密应产生不同密文');
+});
+
+test('密文格式为 iv : ciphertext : authTag 三段 base64', () => {
+  const { encryptToken } = freshCrypto();
+  const enc = encryptToken('jp_test');
+  const parts = enc.split(':');
+  assert.strictEqual(parts.length, 3);
+  // 每段都是合法 base64
+  parts.forEach(p => assert.ok(Buffer.from(p, 'base64').length > 0));
+});
+
+test('密钥文件自动生成在数据目录并持久化', () => {
+  const { encryptToken } = freshCrypto();
+  const enc = encryptToken('jp_persist');
+  const keyFile = path.join(TMP_DATA, 'token-key.key');
+  assert.ok(fs.existsSync(keyFile), '应生成 token-key.key 文件');
+  const hex = fs.readFileSync(keyFile, 'utf8').trim();
+  assert.match(hex, /^[0-9a-fA-F]{64}$/, '密钥文件为 32 字节 hex');
+
+  // 再次 require（重新读文件）应能解密旧密文
+  const { decryptToken: decryptAgain } = freshCrypto();
+  assert.strictEqual(decryptAgain(enc), 'jp_persist');
+});
+
+test('密文被篡改 → 解密抛错（GCM 完整性校验）', () => {
+  const { encryptToken, decryptToken } = freshCrypto();
+  const enc = encryptToken('jp_tamper');
+  const parts = enc.split(':');
+  // 篡改 ciphertext 段的第一个字符
+  const tamperedData = Buffer.from(parts[1], 'base64');
+  tamperedData[0] ^= 0xff;
+  const tampered = [parts[0], tamperedData.toString('base64'), parts[2]].join(':');
+  assert.throws(() => decryptToken(tampered), /unsupported|auth|decrypt|final/i);
+});
+
+test('格式错误的密文 → 解密抛错', () => {
+  const { decryptToken } = freshCrypto();
+  assert.throws(() => decryptToken('not-a-valid-ciphertext'));
+  assert.throws(() => decryptToken('a:b'));
+});
+
+test('环境变量 TOKEN_ENCRYPTION_KEY 优先于密钥文件（合法 hex）', () => {
+  process.env.TOKEN_ENCRYPTION_KEY = crypto.randomBytes(32).toString('hex');
+  const { encryptToken, decryptToken } = freshCrypto();
+  const enc = encryptToken('jp_env_key');
+  assert.strictEqual(decryptToken(enc), 'jp_env_key');
+  assert.ok(!fs.existsSync(path.join(TMP_DATA, 'token-key.key')), '用环境变量时不应生成密钥文件');
+});
+
+test('reloadKey() 切换密钥后旧密文无法解密', () => {
+  const mod = freshCrypto();
+  const enc = mod.encryptToken('jp_rotate');
+  // 换一个新环境变量密钥并 reload
+  process.env.TOKEN_ENCRYPTION_KEY = crypto.randomBytes(32).toString('hex');
+  mod.reloadKey();
+  assert.throws(() => mod.decryptToken(enc), '换密钥后旧密文应无法解密');
+});

package/test/unit/fts.test.js

@@ -0,0 +1,52 @@
+// lib/fts.js 单元测试
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const { escapeFtsQuery, isFtsIndexable } = require('../../lib/fts');
+
+test('isFtsIndexable：可索引扩展名', () => {
+  assert.ok(isFtsIndexable('html', 'a.html'));
+  assert.ok(isFtsIndexable('markdown', 'b.md'));
+  assert.ok(isFtsIndexable('html', 'c.MD')); // 大写
+  assert.ok(isFtsIndexable('markdown', 'd.markdown'));
+  assert.ok(isFtsIndexable('text', 'e.txt'));
+  assert.ok(isFtsIndexable('html', 'f.HTM'));
+});
+
+test('isFtsIndexable：不可索引', () => {
+  assert.ok(!isFtsIndexable('bundle', 'a.html')); // bundle 永不索引
+  assert.ok(!isFtsIndexable('html', 'a.png'));
+  assert.ok(!isFtsIndexable('html', 'noext'));
+  assert.ok(!isFtsIndexable('html', ''));
+});
+
+test('escapeFtsQuery：移除 FTS5 特殊字符（特殊字符替换为空格后分词）', () => {
+  const r = escapeFtsQuery('hello"world*test');
+  // " 和 * 是 FTS5 特殊字符，替换为空格后分成三个 token
+  assert.strictEqual(r, '"hello" "world" "test"');
+});
+
+test('escapeFtsQuery：空查询返回空串', () => {
+  assert.strictEqual(escapeFtsQuery(''), '');
+  assert.strictEqual(escapeFtsQuery('   '), '');
+  assert.strictEqual(escapeFtsQuery('"*()'), '');
+});
+
+test('escapeFtsQuery：每个 token 被双引号包裹', () => {
+  const r = escapeFtsQuery('hello world');
+  assert.strictEqual(r, '"hello" "world"');
+});
+
+test('escapeFtsQuery：CJK 逐字分词', () => {
+  const r = escapeFtsQuery('测试');
+  // 每个 CJK 字符前后加空格，最终每个字单独成 token
+  assert.ok(r.includes('"测"'));
+  assert.ok(r.includes('"试"'));
+});
+
+test('escapeFtsQuery：CJK + ASCII 混合', () => {
+  const r = escapeFtsQuery('api 测试');
+  assert.ok(r.includes('"api"'));
+  assert.ok(r.includes('"测"'));
+  assert.ok(r.includes('"试"'));
+});

package/test/unit/render-cache.test.js

@@ -0,0 +1,76 @@
+// lib/render-cache.js 单元测试
+const test = require('node:test');
+const assert = require('node:assert');
+const {
+  renderCacheKey,
+  getRenderedHtml,
+  setRenderedHtml,
+  invalidateRenderCache,
+  clearRenderCache,
+} = require('../../lib/render-cache');
+
+function fakeFile(id, overrides = {}) {
+  return {
+    id,
+    stored_name: `f${id}.md`,
+    updated_at: '2026-01-01 00:00:00',
+    is_bundle: 0,
+    entry_path: null,
+    ...overrides,
+  };
+}
+
+test('renderCacheKey：含 id/stored_name/updated_at/is_bundle/entry_path', () => {
+  const key = renderCacheKey(fakeFile(1));
+  assert.ok(key.startsWith('1:f1.md:2026-01-01 00:00:00:0:'));
+});
+
+test('renderCacheKey：stored_name 不同则 key 不同（历史版本场景）', () => {
+  const a = renderCacheKey(fakeFile(1, { stored_name: 'current.md' }));
+  const b = renderCacheKey(fakeFile(1, { stored_name: 'v2.md' }));
+  assert.notStrictEqual(a, b);
+});
+
+test('getRenderedHtml：未缓存返回 null', () => {
+  clearRenderCache();
+  assert.strictEqual(getRenderedHtml(fakeFile(99)), null);
+});
+
+test('setRenderedHtml / getRenderedHtml：写入后命中', () => {
+  clearRenderCache();
+  const f = fakeFile(2);
+  setRenderedHtml(f, '<html></html>');
+  assert.strictEqual(getRenderedHtml(f), '<html></html>');
+});
+
+test('setRenderedHtml：updated_at 变化后旧缓存失效', () => {
+  clearRenderCache();
+  const f1 = fakeFile(3, { updated_at: '2026-01-01 00:00:00' });
+  setRenderedHtml(f1, 'old');
+  const f2 = fakeFile(3, { updated_at: '2026-01-02 00:00:00' });
+  assert.strictEqual(getRenderedHtml(f2), null);
+});
+
+test('invalidateRenderCache：按 fileId 清除该文件全部缓存', () => {
+  clearRenderCache();
+  setRenderedHtml(fakeFile(5, { stored_name: 'a.md' }), 'a');
+  setRenderedHtml(fakeFile(5, { stored_name: 'b.md' }), 'b');
+  setRenderedHtml(fakeFile(6), 'other');
+  invalidateRenderCache(5);
+  assert.strictEqual(getRenderedHtml(fakeFile(5, { stored_name: 'a.md' })), null);
+  assert.strictEqual(getRenderedHtml(fakeFile(5, { stored_name: 'b.md' })), null);
+  assert.ok(getRenderedHtml(fakeFile(6))); // 其它文件不受影响
+});
+
+test('LRU 淘汰：超过 256 条时淘汰最早的', () => {
+  clearRenderCache();
+  // 填满 256 条
+  for (let i = 0; i < 256; i++) {
+    setRenderedHtml(fakeFile(1000 + i), `html${i}`);
+  }
+  // 第 257 条触发淘汰 id=1000 的
+  setRenderedHtml(fakeFile(2000), 'new');
+  assert.strictEqual(getRenderedHtml(fakeFile(1000)), null);
+  assert.strictEqual(getRenderedHtml(fakeFile(2000)), 'new');
+  clearRenderCache();
+});