Add validated atomic commits for XLSX path inserts

Author: shps951023

Cargo.lock

@@ -11,6 +11,7 @@ repository = "https://github.com/mini-software/MiniExcel-Rust"
 homepage = "https://github.com/mini-software/MiniExcel-Rust"
 
 [workspace.dependencies]
+atomicwrites = "0.4.4"
 calamine = { version = "0.35.0", features = ["chrono"] }
 chrono = { version = "0.4.42", features = ["serde"] }
 clap = { version = "4.6.6", features = ["derive"] }

Cargo.toml

@@ -239,19 +239,21 @@ Acceptance:
 
 Depends on Task 4.
 
-- [ ] Write path inserts to a uniquely named sibling temporary file opened with `create_new`.
-- [ ] Finish the ZIP central directory, flush, sync the temporary file, and reopen it for structural validation.
-- [ ] Validate workbook/rels/content-types consistency, unique IDs/targets, worksheet availability, and at least one visible worksheet.
-- [ ] Commit with a safe cross-platform replacement primitive. Workspace code must remain `unsafe`-free; evaluate the existing `tempfile` API first and add a narrowly scoped dependency only if required.
-- [ ] Preserve original file permissions where supported.
-- [ ] Clean temporary package and row-spool files on all error paths.
-- [ ] Add failure injection at preflight, row generation, ZIP copy, ZIP finish, validation, and commit.
+- [x] Write path inserts to a uniquely named sibling temporary file opened with `create_new`.
+- [x] Finish the ZIP central directory, flush, sync the temporary file, and reopen it for structural validation.
+- [x] Validate workbook/rels/content-types consistency, unique IDs/targets, worksheet availability, and at least one visible worksheet.
+- [x] Commit with a safe cross-platform replacement primitive. Workspace code must remain `unsafe`-free; evaluate the existing `tempfile` API first and add a narrowly scoped dependency only if required.
+- [x] Preserve original file permissions where supported.
+- [x] Clean temporary package and row-spool files on all error paths.
+- [x] Add failure injection at preflight, row generation, ZIP copy, ZIP finish, validation, and commit.
+
+Completed on 2026-08-24. Focused test: `cargo +1.85.0 test -p miniexcel insert::atomic::tests --lib --locked`. Windows replacement uses the safe `atomicwrites` wrapper so staged attributes are preserved; Unix mode-bit coverage runs under `cfg(unix)` in CI.
 
 Acceptance:
 
 - The original workbook hash remains unchanged for every injected pre-commit failure.
 - Successful replacement works on Linux and Windows CI.
-- Focused command: `cargo +1.85.0 test -p miniexcel --test insert atomic_commit --locked`.
+- Focused command: `cargo +1.85.0 test -p miniexcel insert::atomic::tests --lib --locked`.
 
 ### Task 6: Public Append API
 

docs/insert-existing-workbook-plan.md

@@ -239,19 +239,21 @@ Donor-workbook 方案复用经过测试的 `XlsxWriter`，避免重复实现 ser
 
 依赖 Task 4。
 
-- [ ] Path insert 写入同目录、使用 `create_new` 打开的唯一临时文件。
-- [ ] 完成 ZIP central directory、flush、sync 临时文件，并重新打开做结构验证。
-- [ ] 验证 workbook/rels/content-types 一致性、ID/target 唯一、worksheet 可访问，且至少一个 visible worksheet。
-- [ ] 使用安全的跨平台 replacement primitive。Workspace code 必须保持无 `unsafe`；先评估现有 `tempfile` API，只在必要时增加范围很窄的 dependency。
-- [ ] 可行时保留 source permission。
-- [ ] 所有 error path 清理临时 package 和 row spool。
-- [ ] 在 preflight、row generation、ZIP copy、ZIP finish、validation 和 commit 阶段加入 failure injection。
+- [x] Path insert 写入同目录、使用 `create_new` 打开的唯一临时文件。
+- [x] 完成 ZIP central directory、flush、sync 临时文件，并重新打开做结构验证。
+- [x] 验证 workbook/rels/content-types 一致性、ID/target 唯一、worksheet 可访问，且至少一个 visible worksheet。
+- [x] 使用安全的跨平台 replacement primitive。Workspace code 必须保持无 `unsafe`；先评估现有 `tempfile` API，只在必要时增加范围很窄的 dependency。
+- [x] 可行时保留 source permission。
+- [x] 所有 error path 清理临时 package 和 row spool。
+- [x] 在 preflight、row generation、ZIP copy、ZIP finish、validation 和 commit 阶段加入 failure injection。
+
+已于 2026-08-24 完成。聚焦测试：`cargo +1.85.0 test -p miniexcel insert::atomic::tests --lib --locked`。Windows replacement 使用安全的 `atomicwrites` wrapper 以保留 staged attribute；Unix mode-bit 覆盖在 CI 的 `cfg(unix)` 下执行。
 
 验收：
 
 - 每个 commit 前注入失败都保持原 workbook hash 不变。
 - Linux 与 Windows CI 上成功 replacement。
-- 聚焦命令：`cargo +1.85.0 test -p miniexcel --test insert atomic_commit --locked`。
+- 聚焦命令：`cargo +1.85.0 test -p miniexcel insert::atomic::tests --lib --locked`。
 
 ### Task 6：公共 Append API
 

docs/insert-existing-workbook-plan.zh-CN.md

@@ -27,6 +27,9 @@ zip.workspace = true
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 tempfile.workspace = true
 
+[target.'cfg(windows)'.dependencies]
+atomicwrites.workspace = true
+
 [dev-dependencies]
 serde_json.workspace = true
 tempfile.workspace = true

miniexcel/Cargo.toml

@@ -70,6 +70,7 @@ enum ErrorKind {
     ExistingWorksheet(String),
 
     #[error("atomic workbook commit failed: {0}")]
+    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
     AtomicCommit(String),
 
     #[error("failed to deserialize worksheet '{sheet}' at Excel row {row}: {source}")]
@@ -166,7 +167,7 @@ impl Error {
         ErrorKind::ExistingWorksheet(sheet_name.into()).into()
     }
 
-    #[allow(dead_code)]
+    #[cfg_attr(target_arch = "wasm32", allow(dead_code))]
     pub(crate) fn atomic_commit(message: impl Into<String>) -> Self {
         ErrorKind::AtomicCommit(message.into()).into()
     }