docs output writer: add portable directory-handle anchored commit
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
## 背景
文档工具的隔离落盘进程目前以任务工作目录为 cwd,按相对路径逐级创建父目录,拒绝符号链接,并在最终写入前后复核根目录与父目录身份。默认写入使用排他创建,覆盖使用同目录 staging 文件与替换。
## 缺口
Node/Electron 没有跨 macOS、Windows 都可用的“相对已打开目录句柄执行最终 open/rename”接口。当前路径字符串操作因此仍存在一个残余竞态:父目录在复核后、最终文件操作前被替换成工作区外的符号链接时,`O_NOFOLLOW` 只保护最后一个路径分量,无法阻止父级链接跟随。事后身份复核会让工具返回失败,但不能撤销已经发生的外部文件副作用。
## 目标
为文档输出 writer 提供跨支持平台的目录句柄锚定能力,使父目录验证与最终创建/替换在同一受保护解析中完成;保留默认不覆盖、覆盖可恢复和路径越界 fail-closed 语义。
## 验收
- macOS、Windows 均不跟随父级 symlink 越界写入;
- 并发替换父目录时不会在工作区外创建或替换文件;
- 缺失父目录、默认不覆盖、覆盖失败恢复和网络/共享盘降级行为保持现有契约;
- 有跨平台回归测试覆盖父目录替换竞态。
Contributor guide
Research direction
No source files, entry points, or tests are named in the issue. Start by locating the document-output writer and its existing path-validation, staging, replacement, and platform-fallback tests. Done means preserving the stated fail-closed, no-overwrite, recovery, and network/shared-drive behavior while adding macOS and Windows regression coverage for parent-directory replacement races.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, node.js, typescript
- Domain
- security, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100