695 lines
30 KiB
JavaScript
695 lines
30 KiB
JavaScript
// 文件操作 helper（Stage 7 抽出 + Folder Browser 扩展）
|
||
//
|
||
// 职责：
|
||
// - 暴露 file IPC 所需的可测试纯函数（isWithinDataDir / resolveFileName / scanFiles / scanDir / classifyEntry）
|
||
// - 不包含 ipcMain 注册逻辑（仍留在 main.js，与 config-store 的拆分风格一致）
|
||
//
|
||
// 边界：
|
||
// - 不引用 mainWindow / ipcMain / shell —— 这些留在 main.js 里就近注册
|
||
// - 不读 configStore —— 由调用方注入数据目录
|
||
// - scanFiles 的 ENOENT 行为：返回错误（不再静默 mkdir）——
|
||
// 防止「数据目录被外部删了之后被自动重建掩盖数据丢失」
|
||
// 见 audit #3
|
||
//
|
||
// Folder Browser（2026-08）：
|
||
// - scanDir(absDir) 返回一层所有条目（文件夹 + 文件），含 entryType 分类
|
||
// - 文件分类由 classifyEntry(name) 完成：'folder' | 'editable' | 'binary'
|
||
// - EDITABLE_EXTS（来自 shared/extension-lists.js）是「可打开 + 编辑」
|
||
// 的扩展名白名单；markdown (.md/.markdown) 与常见纯文本均在内
|
||
//
|
||
// 测试：tests/unit/file-ops.test.js（jsdom 环境之外；纯 Node 即可）
|
||
|
||
const fs = require('fs').promises;
|
||
const path = require('path');
|
||
// 单一事实源：扩展名白名单（main + preload + renderer 三处共用）
|
||
const { EDITABLE_EXTS } = require('../shared/extension-lists.js');
|
||
// 单一事实源：errno → 中文提示（main + renderer 共享，preload 过桥）
|
||
const { friendlyFsError: sharedFriendlyFsError } = require('../shared/friendly-fs-error.js');
|
||
|
||
/** 单文件大小上限（5 MB），防止超大文件冻结 renderer。 */
|
||
const MAX_FILE_SIZE = 5 * 1024 * 1024;
|
||
|
||
/**
|
||
* 检查 fullPath 的占用情况 —— 返回三种状态：
|
||
* - 'free' 路径不存在，可用
|
||
* - 'file' 路径已被一个文件占用，需要重命名避让
|
||
* - 'directory' 路径已被一个目录占用（用户手动 mkdir 出来），也需要避让
|
||
*
|
||
* 审计修复 (Round 11 deep-fix P2-4)：旧版用 fs.access() 只能判断「存在与否」，
|
||
* 不能区分 file vs directory。用户新建笔记取名 `foo.md` 但数据目录里已经有一个
|
||
* 同名目录（手动 mkdir 出来的笔记文件夹），resolveFileName 直接把目录路径当成
|
||
* 可用文件返回；后续 atomicWriteFile 打开目录路径得到 EISDIR，UI 弹「无效参数」
|
||
* 误导信息。改用 fs.stat() 拿 dirent 类型确认。
|
||
*/
|
||
async function pathOccupancy(fullPath) {
|
||
try {
|
||
const st = await fs.stat(fullPath);
|
||
if (st.isDirectory()) return 'directory';
|
||
if (st.isFile()) return 'file';
|
||
// socket / fifo / device —— 数据目录里不应出现，但既然存在也当占用
|
||
return 'file';
|
||
} catch (e) {
|
||
if (e && e.code === 'ENOENT') return 'free';
|
||
// EACCES / EPERM 等：保守起见当「占用」，让上层走避让分支
|
||
return 'file';
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 给一个文件名分类为 folder / editable / binary。
|
||
* 纯函数：不读文件系统、不感知 path —— 仅看 name 末尾扩展名。
|
||
*
|
||
* 注意：folder 类型由调用方（scanDir）传入时显式标记，
|
||
* 本函数在 entryType === 'folder' 时不会被调用（参见 scanDir 内部）。
|
||
*
|
||
* @param {string} name
|
||
* @returns {'editable'|'binary'}
|
||
*/
|
||
function classifyEntry(name) {
|
||
if (typeof name !== 'string' || !name) return 'binary';
|
||
const dot = name.lastIndexOf('.');
|
||
// 没有扩展名 → binary
|
||
if (dot < 0) return 'binary';
|
||
const ext = name.slice(dot + 1).toLowerCase();
|
||
// 隐藏文件 / 末尾多余点：扩展名部分为空（".env" 有扩展名 "env"，不是这种）
|
||
if (!ext) return 'binary';
|
||
// dot === 0 的隐藏文件名（如 ".gitignore"）：扩展名部分非空但不在白名单 → binary
|
||
// 注意 ".env" 现在会走 EDITABLE_EXTS.has('env') → 'editable'（修旧版的列表/链接割裂 bug）
|
||
return EDITABLE_EXTS.has(ext) ? 'editable' : 'binary';
|
||
}
|
||
|
||
/**
|
||
* 拒绝 symlink：Notes 用户的工作流是「编辑自己数据目录里的 .md」，
|
||
* 数据目录里出现 symlink 通常来自外部同步盘 / 误操作 / 恶意数据，
|
||
* 写 symlink 会跟随到外部真实文件，绕过 isWithinDataDir 边界。
|
||
* 见 audit #7。
|
||
*
|
||
* @param {string} filePath
|
||
* @returns {Promise<{ok: true, isFile: boolean} | {ok: false, error: string, code?: string}>}
|
||
*/
|
||
async function assertNotSymlink(filePath) {
|
||
let st;
|
||
try {
|
||
st = await fs.lstat(filePath);
|
||
} catch (e) {
|
||
if (e.code === 'ENOENT') return { ok: true, isFile: false }; // 不存在：留给调用方走 FILE_NOT_FOUND 路径
|
||
return { ok: false, error: e.message, code: e.code };
|
||
}
|
||
if (st.isSymbolicLink()) {
|
||
return { ok: false, error: 'SYMLINK_NOT_ALLOWED', message: '不允许编辑符号链接（防止越权写入）' };
|
||
}
|
||
return { ok: true, isFile: st.isFile() };
|
||
}
|
||
|
||
/**
|
||
* audit fix (M1 main)：递归检查 filePath 与其祖先（直到 stopAt 目录），
|
||
* 任一层级出现 symlink 即拒绝。光检查 target 文件不够 —— 若父目录是 symlink
|
||
* 指向 dataDir 外部，整个 target 的「真实路径」就会跳出 dataDir，绕过
|
||
* isWithinDataDir 的字符串前缀检查。同步盘 / 误操作 / 外部攻击都可能制造
|
||
* 这种中间层 symlink。
|
||
*
|
||
* 策略：从 filePath 父目录开始向上 lstat，到 stopAt（一般是 dataDir）为止，
|
||
* 任一是 symlink 就拒绝。stopAt 本身允许是 symlink？通常不允许，但它的边界
|
||
* 由 assertDataDirSafe 等其它检查负责，这里只覆盖 target 这棵子树。
|
||
*
|
||
* @param {string} filePath - 目标文件路径
|
||
* @param {string} [stopAt] - 终止祖先链的目录（默认不传 = 一路 lstat 到根，
|
||
* 但调用方一般会传 dataDir 来限定范围）
|
||
* @returns {Promise<{ok:true} | {ok:false, error:string, code?:string}>}
|
||
*/
|
||
async function assertNoSymlinkAncestor(filePath, stopAt) {
|
||
if (!filePath) return { ok: false, error: 'INVALID_PATH', code: 'INVALID_PATH', message: '路径不能为空' };
|
||
const stopResolved = stopAt ? path.resolve(stopAt) : null;
|
||
// audit fix (Phase O fix)：原实现只从 filePath 的**父目录**开始向上 lstat，
|
||
// 漏掉 filePath 自身。若 filePath 本身是 symlink（指向外部目标盘），父目录
|
||
// 通常都是合法的 dataDir 子项，但 filePath 本身跟随 symlink 解析后就跳到
|
||
// dataDir 之外 —— isWithinDataDir 的字符串前缀边界被绕过。
|
||
// 先 lstat filePath 自身：在 stopResolved 子树里也要拒绝自身是 symlink 的场景。
|
||
const resolvedPath = path.resolve(filePath);
|
||
if (!stopResolved || resolvedPath !== stopResolved) {
|
||
try {
|
||
const stSelf = await fs.lstat(resolvedPath);
|
||
if (stSelf.isSymbolicLink()) {
|
||
return {
|
||
ok: false,
|
||
error: 'SYMLINK_NOT_ALLOWED',
|
||
code: 'SYMLINK_NOT_ALLOWED',
|
||
message: `路径中包含符号链接，不允许编辑（${resolvedPath}）`,
|
||
};
|
||
}
|
||
} catch (e) {
|
||
// ENOENT：目标本身不存在是允许的（scan-dir 创建场景、新文件）；其它错误上报
|
||
if (e.code !== 'ENOENT') {
|
||
return { ok: false, error: e.message, code: e.code, message: `读取路径状态失败：${e.code || e.message}` };
|
||
}
|
||
}
|
||
}
|
||
let dir = path.dirname(resolvedPath);
|
||
// 已经走到根盘符 / 根目录就停
|
||
const seen = new Set();
|
||
while (dir && !seen.has(dir)) {
|
||
seen.add(dir);
|
||
// 终止祖先链的判定：stopAt 目录已检查过、不再向上 lstat。
|
||
// audit fix (main-M10)：之前三连 OR 里 `dir === stopResolved.toLowerCase?.()`
|
||
// 是死分支 —— dir 来自 path.dirname()，Windows 上是混合大小写，根本不会
|
||
// 全小写化。删掉，只保留 POSIX 严格相等 + Windows 大小写无关两条。
|
||
if (stopResolved && (dir === stopResolved
|
||
|| (process.platform === 'win32' && dir.toLowerCase() === stopResolved.toLowerCase()))) {
|
||
break;
|
||
}
|
||
try {
|
||
const st = await fs.lstat(dir);
|
||
if (st.isSymbolicLink()) {
|
||
return {
|
||
ok: false,
|
||
error: 'SYMLINK_NOT_ALLOWED',
|
||
code: 'SYMLINK_NOT_ALLOWED',
|
||
message: `路径中包含符号链接目录，不允许编辑（${dir}）`,
|
||
};
|
||
}
|
||
} catch (e) {
|
||
// 父目录不存在是允许的（target 可能尚未创建）；其它错误上报
|
||
if (e.code !== 'ENOENT') {
|
||
// audit fix (K1-R4)：统一带 code + message 字段，与 assertNotSymlink 对齐。
|
||
return { ok: false, error: e.message, code: e.code, message: `读取目录状态失败：${e.code || e.message}` };
|
||
}
|
||
break;
|
||
}
|
||
const parent = path.dirname(dir);
|
||
if (parent === dir) break; // 已经到盘符根
|
||
dir = parent;
|
||
}
|
||
return { ok: true };
|
||
}
|
||
|
||
/**
|
||
* 检查目标路径是否在数据目录内（防止越权读写）
|
||
* - Windows 不区分大小写
|
||
* - 字符串前缀比对（path.resolve 后再做）
|
||
* - 未调用 fs.realpath（symlink 不解）；file:write/rename/delete 已先 lstat 拒绝 symlink
|
||
*
|
||
* @param {string} target
|
||
* @param {string} root
|
||
*/
|
||
function isWithinDataDir(target, root) {
|
||
if (!root || !target) return false;
|
||
const rootResolved = path.resolve(root);
|
||
const targetResolved = path.resolve(target);
|
||
if (process.platform === 'win32') {
|
||
const rootLower = rootResolved.toLowerCase();
|
||
const targetLower = targetResolved.toLowerCase();
|
||
return targetLower.startsWith(rootLower + path.sep)
|
||
|| targetLower === rootLower;
|
||
}
|
||
return targetResolved === rootResolved
|
||
|| targetResolved.startsWith(rootResolved + path.sep);
|
||
}
|
||
|
||
/**
|
||
* 文件名清洗：拒绝路径分隔符 / `..` / 空字符串 / 控制字符；用户输入的扩展名
|
||
* 原样保留；重名 (2)、(3)...。
|
||
*
|
||
* audit fix (Phase L3-FS 4A/4B)：拒绝 Windows 保留字符（<>:"/\\|?*）和保留设备名
|
||
* (CON / PRN / AUX / NUL / COM1-9 / LPT1-9)。之前 name 里含 `|` 或 `:` 仍能通过
|
||
* resolveFileName，到 fs.rename 才在 Windows 上撞 EPERM/EBUSY，UI 弹出
|
||
* 「没有重命名权限 / 文件被占用」误导性中文。预先拒绝给清晰的中文错误。
|
||
*
|
||
* 用户反馈（2026-08-28）：「新建笔记时直接把后缀放在文件名后面，而不是自动
|
||
* 加上」—— 本函数不再强制补 .md。用户输入 `foo.md` / `foo.txt` / `foo`（无扩展名）
|
||
* 都按字面保留。重名避让时扩展名也原样保留（foo.txt → foo (2).txt）。
|
||
* 重命名场景走 resolveRenameName，行为完全对称。
|
||
*
|
||
* @param {string} raw
|
||
* @param {string} dir - 数据目录绝对路径
|
||
* @returns {Promise<{ok:true, path:string, name:string} | {ok:false, error:string}>}
|
||
*/
|
||
// Windows 保留设备名（基础名，无扩展名时）。注意是大写比对；用户的实际
|
||
// 输入通常是大小写混合，做 toUpperCase 后再校验。带扩展名也照样拒
|
||
// （Windows 把 CON.md / con.txt 都视作设备名 —— 这是 NTFS 的硬规则，
|
||
// fs.rename 一定撞 EPERM）。
|
||
const WIN_RESERVED_DEVICE_NAMES = new Set([
|
||
'CON', 'PRN', 'AUX', 'NUL',
|
||
'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
|
||
'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
|
||
]);
|
||
|
||
async function resolveFileName(raw, dir) {
|
||
if (typeof raw !== 'string' || !raw.trim()) {
|
||
return { ok: false, error: '文件名不能为空' };
|
||
}
|
||
const name = raw.trim();
|
||
// 拒绝路径分隔符与 .. 段
|
||
if (/[/\\]/.test(name) || name.includes('..')) {
|
||
return { ok: false, error: '文件名不能包含路径分隔符或 ..' };
|
||
}
|
||
// Windows 保留字符：<>:"/\\|?*（/\\ 已被上面挡一次，这里再列一遍保持语义独立，
|
||
// 让错误信息精确指向 Windows 保留字符而非「路径分隔符」）。
|
||
if (/[<>:"|?*]/.test(name)) {
|
||
return { ok: false, error: '文件名包含 Windows 保留字符（< > : " | ? *）' };
|
||
}
|
||
// 控制字符
|
||
// eslint-disable-next-line no-control-regex
|
||
if (/[\x00-\x1f]/.test(name)) {
|
||
return { ok: false, error: '文件名包含非法字符' };
|
||
}
|
||
// Windows 保留设备名：取最后一个 . 之前的部分（"CON.md" / "CON" / "CON.txt" 都算）
|
||
const lastDot = name.lastIndexOf('.');
|
||
const baseForReserved = (lastDot > 0 ? name.slice(0, lastDot) : name).toUpperCase();
|
||
if (WIN_RESERVED_DEVICE_NAMES.has(baseForReserved)) {
|
||
return { ok: false, error: `"${baseForReserved}" 是 Windows 保留设备名，不允许作为文件名` };
|
||
}
|
||
// 用户输入的扩展名原样保留 —— 故意不强制 .md（与 resolveRenameName 对齐）。
|
||
|
||
let candidate = name;
|
||
let counter = 2;
|
||
for (;;) {
|
||
const fullPath = path.join(dir, candidate);
|
||
// 任何候选路径都必须仍在数据目录内（防止 join 出 ..\）
|
||
if (!isWithinDataDir(fullPath, dir)) {
|
||
return { ok: false, error: '非法路径' };
|
||
}
|
||
const occupancy = await pathOccupancy(fullPath);
|
||
if (occupancy === 'free') {
|
||
return { ok: true, path: fullPath, name: candidate };
|
||
}
|
||
// 'file' / 'directory' 都视为占用 → 走避让分支
|
||
// 重名避让：取最后一个 . 之前的部分加 (N)，扩展名原样保留（与 resolveRenameName 对齐）。
|
||
// foo.md → foo (2).md；bar.txt → bar (2).txt；baz（无扩展名） → baz (2)
|
||
const cutAt = lastDot > 0 ? lastDot : name.length;
|
||
const base = name.slice(0, cutAt);
|
||
const ext = name.slice(cutAt);
|
||
candidate = `${base} (${counter})${ext}`;
|
||
counter += 1;
|
||
if (counter > 1000) return { ok: false, error: '重名次数过多' };
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 重命名专用的文件名清洗。
|
||
*
|
||
* 用户反馈：「重命名不要自动补后缀」—— 重命名场景下用户输入什么就用什么，
|
||
* 包括完全去掉扩展名（foo.md → bar）或换成别的扩展名（foo.md → bar.txt）。
|
||
*
|
||
* 2026-08-28 反馈后，resolveFileName（新建文件）与本函数语义完全对齐：
|
||
* 都不强制补 .md，新建时用户输入什么就用什么（默认 .md 仍由 renderer 的
|
||
* defaultName 带出来）。这样用户想新建一个 .txt 纯文本笔记 / .json 数据笔记
|
||
* 不再需要「先建 .md → 重命名成 .txt」两步。
|
||
*
|
||
* 仍然保留的校验：
|
||
* - 路径分隔符 / ..
|
||
* - Windows 保留字符
|
||
* - Windows 保留设备名（基础名按 . 之前的部分取，"CON.md" 也算）
|
||
* - 控制字符
|
||
* - 重名避让（(2)/(3) 后缀保留原始扩展名：foo.md → foo (2).md；
|
||
* foo.txt → foo (2).txt；无扩展名 foo → foo (2)）
|
||
*
|
||
* @param {string} raw
|
||
* @param {string} dir
|
||
*/
|
||
async function resolveRenameName(raw, dir) {
|
||
if (typeof raw !== 'string' || !raw.trim()) {
|
||
return { ok: false, error: '文件名不能为空' };
|
||
}
|
||
const name = raw.trim();
|
||
// 拒绝路径分隔符与 .. 段
|
||
if (/[/\\]/.test(name) || name.includes('..')) {
|
||
return { ok: false, error: '文件名不能包含路径分隔符或 ..' };
|
||
}
|
||
if (/[<>:"|?*]/.test(name)) {
|
||
return { ok: false, error: '文件名包含 Windows 保留字符（< > : " | ? *）' };
|
||
}
|
||
// 控制字符
|
||
// eslint-disable-next-line no-control-regex
|
||
if (/[\x00-\x1f]/.test(name)) {
|
||
return { ok: false, error: '文件名包含非法字符' };
|
||
}
|
||
// Windows 保留设备名：取最后一个 . 之前的部分（"CON.md" / "CON" / "CON.txt" 都算）
|
||
const lastDot = name.lastIndexOf('.');
|
||
const baseForReserved = (lastDot > 0 ? name.slice(0, lastDot) : name).toUpperCase();
|
||
if (WIN_RESERVED_DEVICE_NAMES.has(baseForReserved)) {
|
||
return { ok: false, error: `"${baseForReserved}" 是 Windows 保留设备名，不允许作为文件名` };
|
||
}
|
||
|
||
let candidate = name;
|
||
let counter = 2;
|
||
for (;;) {
|
||
const fullPath = path.join(dir, candidate);
|
||
if (!isWithinDataDir(fullPath, dir)) {
|
||
return { ok: false, error: '非法路径' };
|
||
}
|
||
// 审计修复 (Round 11 deep-fix P2-4)：用 pathOccupancy 替代 fs.access，
|
||
// 区分 file vs directory —— 同名目录不能被当作可用文件返回。
|
||
const occupancy = await pathOccupancy(fullPath);
|
||
if (occupancy === 'free') {
|
||
return { ok: true, path: fullPath, name: candidate };
|
||
}
|
||
// 重名避让：取最后一个 . 之前的部分加 (N)，扩展名原样保留。
|
||
// foo.md → foo (2).md；bar.txt → bar (2).txt；baz（无扩展名） → baz (2)
|
||
const cutAt = lastDot > 0 ? lastDot : name.length;
|
||
const base = name.slice(0, cutAt);
|
||
const ext = name.slice(cutAt);
|
||
candidate = `${base} (${counter})${ext}`;
|
||
counter += 1;
|
||
if (counter > 1000) return { ok: false, error: '重名次数过多' };
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 扫描数据目录下的所有 .md / .markdown 文件，按名称排序（locale zh-CN）。
|
||
*
|
||
* 重要变更（audit #3）：目录不存在（ENOENT）时不再自动 mkdir，
|
||
* 直接返回错误让上层决定如何处理（弹对话框 / 切换目录），
|
||
* 避免「数据目录被外部删了之后被静默重建掩盖数据丢失」。
|
||
*
|
||
* @param {string} dir
|
||
* @returns {Promise<{ok:true, files:Array} | {ok:false, error:string, code?:string}>}
|
||
*/
|
||
async function scanFiles(dir) {
|
||
if (!dir || typeof dir !== 'string') {
|
||
return { ok: false, error: 'invalid dir', code: 'EINVAL' };
|
||
}
|
||
try {
|
||
let entries;
|
||
try {
|
||
entries = await fs.readdir(dir, { withFileTypes: true });
|
||
} catch (e) {
|
||
// ENOENT：目录不存在 —— 不再自动重建，让用户看到明确错误
|
||
if (e.code === 'ENOENT') {
|
||
return { ok: false, error: 'DATA_DIR_NOT_FOUND', code: 'ENOENT', message: `数据目录不存在：${dir}` };
|
||
}
|
||
throw e;
|
||
}
|
||
const mdFiles = entries.filter((e) => {
|
||
if (!e.isFile()) return false;
|
||
const lower = e.name.toLowerCase();
|
||
return lower.endsWith('.md') || lower.endsWith('.markdown');
|
||
});
|
||
|
||
const files = await Promise.all(mdFiles.map(async (e) => {
|
||
const fullPath = path.join(dir, e.name);
|
||
try {
|
||
const st = await fs.stat(fullPath);
|
||
return {
|
||
name: e.name,
|
||
path: fullPath,
|
||
size: st.size,
|
||
mtimeMs: st.mtimeMs,
|
||
};
|
||
} catch {
|
||
return null;
|
||
}
|
||
}));
|
||
|
||
const list = files
|
||
.filter((f) => f !== null)
|
||
.sort((a, b) => a.name.localeCompare(b.name, 'zh-CN'));
|
||
return { ok: true, files: list };
|
||
} catch (e) {
|
||
return { ok: false, error: e.message, code: e.code };
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 扫描一个目录下的所有直接条目（文件夹 + 文件），按类型分类。
|
||
* Folder Browser（2026-08）的核心入口。
|
||
*
|
||
* 行为约定：
|
||
* - 不递归：只列 absDir 的一层直接子项；想看深层 → 点文件夹进入
|
||
* - 跳过符号链接文件夹（与 assertNotSymlink 同源策略；
|
||
* 不跟随，避免 symlink 指向 dataDir 外部造成越权）
|
||
* - 跳过符号链接文件（同样防御）
|
||
* - 文件 entryType 由 classifyEntry(name) 决定：
|
||
* 'editable' = Markdown 或常见纯文本（白名单内）
|
||
* 'binary' = 其它扩展名（侧栏仍显示但灰掉、点击弹 toast）
|
||
* - 文件夹 entryType 固定为 'folder'
|
||
* - 排序：文件夹在前（按名称），文件在后（按名称）；
|
||
* 让用户先看到目录结构再看到内容，更符合 Explorer/Finder 的直觉
|
||
*
|
||
* @param {string} absDir - 数据目录下某一层的绝对路径
|
||
* @returns {Promise<{
|
||
* ok: true,
|
||
* dir: string, // 回传绝对路径，便于调用方对照
|
||
* entries: Array<{
|
||
* name: string,
|
||
* path: string, // 绝对路径
|
||
* entryType: 'folder'|'editable'|'binary',
|
||
* isFolder: boolean,
|
||
* size?: number,
|
||
* mtimeMs?: number,
|
||
* }>
|
||
* } | { ok:false, error, code?, message? }>}
|
||
*/
|
||
async function scanDir(absDir) {
|
||
if (!absDir || typeof absDir !== 'string') {
|
||
return { ok: false, error: 'invalid dir', code: 'EINVAL' };
|
||
}
|
||
let dirents;
|
||
try {
|
||
dirents = await fs.readdir(absDir, { withFileTypes: true });
|
||
} catch (e) {
|
||
if (e.code === 'ENOENT') {
|
||
return { ok: false, error: 'DATA_DIR_NOT_FOUND', code: 'ENOENT', message: `目录不存在：${absDir}` };
|
||
}
|
||
// audit fix (Round 12 P2)：非 ENOENT 路径不再把原始 e.message（英文 errno
|
||
// + 绝对路径）透出去。renderer fs-watcher 推过来时直接当成 toast 文案
|
||
// 显示，会泄漏路径 + 看着割裂。走 friendly-fs-error 与 Round 8 EROFS /
|
||
// ENAMETOOLONG 等统一：未知 errno 时拿 e.message 作为 fallback（兜底
|
||
// 业务码），不能让用户看空白 toast。
|
||
return {
|
||
ok: false,
|
||
error: sharedFriendlyFsError(e && e.code, e && e.message) || '扫描目录失败',
|
||
code: e.code,
|
||
};
|
||
}
|
||
|
||
// 用 lstat 一次性拿每一项的类型，过滤掉符号链接（防止越权）。
|
||
// 注意 fs.readdir(..., {withFileTypes:true}) 给的 dirent.isSymbolicLink()
|
||
// 在 Windows 上对 junction 也判定为 true —— 这里统一跳，避免跟随。
|
||
const safeDirents = [];
|
||
for (const d of dirents) {
|
||
if (d.isSymbolicLink()) continue;
|
||
safeDirents.push(d);
|
||
}
|
||
|
||
const entries = await Promise.all(safeDirents.map(async (d) => {
|
||
const fullPath = path.join(absDir, d.name);
|
||
if (d.isDirectory()) {
|
||
return {
|
||
name: d.name,
|
||
path: fullPath,
|
||
entryType: 'folder',
|
||
isFolder: true,
|
||
};
|
||
}
|
||
if (d.isFile()) {
|
||
try {
|
||
const st = await fs.stat(fullPath);
|
||
return {
|
||
name: d.name,
|
||
path: fullPath,
|
||
entryType: classifyEntry(d.name),
|
||
isFolder: false,
|
||
size: st.size,
|
||
mtimeMs: st.mtimeMs,
|
||
};
|
||
} catch {
|
||
// 文件在 readdir 与 stat 之间被删了 —— 静默跳过
|
||
return null;
|
||
}
|
||
}
|
||
// 其它（socket / fifo / block device 等）—— 不展示
|
||
return null;
|
||
}));
|
||
|
||
const list = entries.filter(Boolean);
|
||
// 排序：folder 在前、file 在后，同组内按 zh-CN locale
|
||
list.sort((a, b) => {
|
||
if (a.isFolder !== b.isFolder) return a.isFolder ? -1 : 1;
|
||
return a.name.localeCompare(b.name, 'zh-CN');
|
||
});
|
||
|
||
return { ok: true, dir: absDir, entries: list };
|
||
}
|
||
|
||
/**
|
||
* 把数据目录根下的相对路径解析成绝对路径，并做防御性校验。
|
||
*
|
||
* 渲染端传来的 relDir 必须满足：
|
||
* - 空字符串 → dataRoot（根目录）
|
||
* - 正斜杠分隔的相对路径（如 'notes/2026'），不含 ..
|
||
* - 不含绝对路径前缀（Windows 盘符 / POSIX /）
|
||
*
|
||
* 解析后用 isWithinDataDir 二次校验（防止路径穿越 / symlink 跟随）。
|
||
*
|
||
* @param {string} relDir
|
||
* @param {string} dataRoot - 数据目录绝对路径
|
||
* @returns {{ok:true, absDir:string, relDir:string} | {ok:false, error:string, message?:string}}
|
||
*/
|
||
function resolveDirRelative(relDir, dataRoot) {
|
||
if (typeof relDir !== 'string') {
|
||
return { ok: false, error: 'INVALID_REL_DIR', message: 'relDir 必须是字符串' };
|
||
}
|
||
// 拒绝盘符 / 绝对路径前缀（必须在 strip 前做，否则 '/etc/passwd' 被剥成
|
||
// 'etc/passwd' 反而通过校验）
|
||
if (/^[a-z]:[\\/]/i.test(relDir) || relDir.startsWith('/') || relDir.startsWith('\\')) {
|
||
return { ok: false, error: 'PATH_NOT_ALLOWED', message: '不允许使用绝对路径' };
|
||
}
|
||
const normalized = relDir.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
|
||
// 拒绝 .. 段（即使藏在中间）
|
||
if (normalized.split('/').some((seg) => seg === '..' || seg === '.')) {
|
||
return { ok: false, error: 'PATH_NOT_ALLOWED', message: '相对路径不能包含 . 或 ..' };
|
||
}
|
||
const absDir = normalized === '' ? dataRoot : path.join(dataRoot, normalized);
|
||
if (!isWithinDataDir(absDir, dataRoot)) {
|
||
return { ok: false, error: 'PATH_NOT_ALLOWED', message: '路径不在数据目录内' };
|
||
}
|
||
// 重新标准化回 POSIX（与传入保持一致）+ 末尾无 /
|
||
const relOut = normalized;
|
||
return { ok: true, absDir, relDir: relOut };
|
||
}
|
||
|
||
/**
|
||
* 给定 dataRoot 与当前目录的绝对路径，反算 POSIX 风格的相对路径。
|
||
* 渲染端用于比对 fs-watcher 推送的 relDir 字段。
|
||
*
|
||
* @param {string} absDir
|
||
* @param {string} dataRoot
|
||
* @returns {string} POSIX 相对路径，根目录时为 ''
|
||
*/
|
||
function toRelativeDir(absDir, dataRoot) {
|
||
if (!absDir || !dataRoot) return '';
|
||
const a = absDir.replace(/\\/g, '/').replace(/\/+$/, '');
|
||
const r = dataRoot.replace(/\\/g, '/').replace(/\/+$/, '');
|
||
if (a === r) return '';
|
||
const prefix = r + '/';
|
||
if (a.startsWith(prefix)) return a.slice(prefix.length);
|
||
// 不在 dataRoot 下（理论上不该发生）—— 返回空字符串让渲染端走根路径分支
|
||
return '';
|
||
}
|
||
|
||
/**
|
||
* 原子写文件 —— audit fix（C1/C2 file-IO）：
|
||
* 1. 写到 dst.tmp.<pid>.<now>
|
||
* 2. fsync tmp（让内容确实落盘，再 rename 才不会丢）
|
||
* 3. renameWithRetry 覆盖 dst（Windows Defender / 杀毒 / 同步盘
|
||
* 偶尔瞬态持锁，retry-on-busy 比直接放弃稳得多）
|
||
*
|
||
* 失败路径：
|
||
* - 写入 tmp 失败 → unlink tmp + 抛原始 errno
|
||
* - rename 失败（retry 后）→ unlink tmp + 抛原始 errno
|
||
*
|
||
* 副作用：成功后磁盘上要么是旧文件（旧文件全程未动），要么是新文件；
|
||
* 永远不会有半截内容被读到。
|
||
*
|
||
* @param {string} dst 目标绝对路径
|
||
* @param {string} content UTF-8 文本
|
||
*/
|
||
async function atomicWriteFile(dst, content) {
|
||
const tmpPath = `${dst}.tmp.${process.pid}.${Date.now()}`;
|
||
let fh;
|
||
try {
|
||
fh = await fs.open(tmpPath, 'w');
|
||
await fh.writeFile(content, 'utf-8');
|
||
// fsync 关键：没有 fsync，rename 之后断电可能留下「磁盘上 inode 改了
|
||
// 但内容还在 page cache、从未刷盘」的零字节文件。Windows 上 fsync 等价
|
||
// FlushFileBuffers，rename 之前必须强制落盘。
|
||
await fh.sync();
|
||
await fh.close();
|
||
fh = null;
|
||
} catch (e) {
|
||
if (fh) { try { await fh.close(); } catch { /* ignore */ } }
|
||
try { await fs.unlink(tmpPath); } catch { /* tmp 不存在也忽略 */ }
|
||
throw e;
|
||
}
|
||
|
||
try {
|
||
await renameWithRetry(tmpPath, dst);
|
||
// audit fix (Round 4 P0-1)：rename 后 fsync 父目录（仅 Linux / POSIX）。
|
||
// POSIX rename(2) 在同分区下原子，但「目录项本身」写入磁盘的时机由内核
|
||
// 控制；不 fsync 目录就断电，磁盘上可能仍是旧名字 → 文件彻底丢失。
|
||
// Windows 上 NTFS 文件系统层 journal 元数据，这条 fsync 不需要（也无害，
|
||
// 但 fs.open(path, 'r') 在目录上 Windows 会拒绝写操作，所以这里走 OS 守卫）。
|
||
// 风险：失败 fsync 不抛（让 save 走 OK 路径），由下次保存自动覆盖。
|
||
if (process.platform !== 'win32') {
|
||
try {
|
||
const dirFh = await fs.open(path.dirname(dst), 'r');
|
||
await dirFh.sync();
|
||
await dirFh.close();
|
||
} catch (dirFsyncErr) {
|
||
console.warn('[file-ops] 父目录 fsync 失败（不影响本次保存内容，但跨崩溃可能丢目录项）:', dirFsyncErr.message);
|
||
}
|
||
}
|
||
} catch (e) {
|
||
// rename 失败：清理残余 tmp（不影响下次保存）
|
||
try { await fs.unlink(tmpPath); } catch { /* 文件可能已被 rename 移走 */ }
|
||
throw e;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* audit fix (C3 file-IO)：rename 重试 EBUSY/EPERM/EACCES。
|
||
* Windows Defender / 杀毒 / 同步盘会在极短时间内持锁目标文件，
|
||
* 单次 rename 失败率约 1-3%。3 次 50/100/200ms backoff 后仍失败才抛。
|
||
* 与 config-store 的同名实现保持一致的 backoff 时序，避免两条路径表现差异。
|
||
* @param {string} src
|
||
* @param {string} dst
|
||
*/
|
||
async function renameWithRetry(src, dst) {
|
||
const delays = [50, 100, 200];
|
||
for (let i = 0; i <= delays.length; i += 1) {
|
||
try {
|
||
await fs.rename(src, dst);
|
||
return;
|
||
} catch (e) {
|
||
const transient = e.code === 'EBUSY' || e.code === 'EPERM' || e.code === 'EACCES';
|
||
// 末次重试仍失败 → 直接抛；非瞬态错误也直接抛（不浪费重试）。
|
||
if (!transient || i === delays.length) throw e;
|
||
await new Promise((r) => setTimeout(r, delays[i]));
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* audit fix (Round 4 收尾)：file:write 的 errno 翻译 —— 与 main.js 各 IPC handler
|
||
* （_friendlyCreateError / _friendlyRenameError / _friendlyDeleteError / _friendlyReadError）
|
||
* 共用一份文案。Round 4 之前本函数与 src/app.js#friendlyWriteError、
|
||
* src/file-ops.js#friendlyFsError 三处独立，EROFS / ENAMETOOLONG / ENOTDIR 文案
|
||
* 三处不同，ENOTEMPTY 在 src/file-ops.js 独有 —— 用户看到的提示不一致。
|
||
*
|
||
* 改用 shared/friendly-fs-error.js 单一事实源（preload 同时把它过桥到
|
||
* window.api.friendlyFsError，renderer 两处旧实现也走同一份）。本函数保留壳子
|
||
* 是为了不重写所有调用点的语义（main 内部仍叫 friendlyWriteError 表达
|
||
* 「写盘错误翻译」，renderer 走 window.api.friendlyFsError 表达通用 errno 翻译）。
|
||
*
|
||
* @param {NodeJS.ErrnoException|null|undefined} e
|
||
* @returns {string} 中文提示（永不为空 —— 兜底走「未知错误」）
|
||
*/
|
||
function friendlyWriteError(e) {
|
||
// 把 e.message 作为 fallback 透传给 sharedFriendlyFsError。
|
||
// - 已知 errno：shared 模块返回固定中文文案，与 e.message 无关
|
||
// - 未知 errno / null e / e.code 缺失：shared 模块走 fallback || '未知错误'
|
||
// → e?.message 有就透传英文 errno + 路径（renderer 拿到的是已经走
|
||
// friendlyFsError 二次翻译过的中文，不会再让英文 errno 漏到这里）；
|
||
// 没有就回退到「未知错误」（注意：旧版这里固定传「写入文件失败」，
|
||
// 与 renderer 三处的「未知错误」兜底文案不一致，统一为后者）
|
||
return sharedFriendlyFsError(e && e.code, e && e.message);
|
||
}
|
||
|
||
module.exports = {
|
||
MAX_FILE_SIZE,
|
||
EDITABLE_EXTS,
|
||
assertNotSymlink,
|
||
assertNoSymlinkAncestor,
|
||
classifyEntry,
|
||
isWithinDataDir,
|
||
resolveFileName,
|
||
resolveRenameName,
|
||
scanFiles,
|
||
scanDir,
|
||
resolveDirRelative,
|
||
toRelativeDir,
|
||
atomicWriteFile,
|
||
renameWithRetry,
|
||
friendlyWriteError,
|
||
};
|