F17.5 — Safe filesystem mutation
| State | Closed |
| Parent | E17 |
| Iteration | Release 8 |
| Start Date | 2026-10-31 |
| Closed Date | 2026-10-31 |
| Predecessors | — |
| Source | Owner request, 2026-10-21 |
Stories: 3 Closed
| Story | State | Depends on |
|---|---|---|
S17.5.1 — Build atomic_replace |
Closed (2026-10-31) | — |
S17.5.2 — Build move_no_clobber |
Closed (2026-10-31) | — |
S17.5.3 — Build prune_empty_parents |
Closed (2026-10-31) | — |
An application that rewrites user files in place needs three small, easy to get
wrong operations: replace a file atomically after editing a copy, move a file
without ever overwriting its destination, and remove the empty directories a
move leaves behind without climbing out of the library. Apollo wrote all three,
and this feature added them to PathUtils in rn-forge-commons.
Outcome: PathUtils.atomic_replace, move_no_clobber and
prune_empty_parents shipped on 2026-10-31. Their contracts are in the
docstrings rendered by the rn-forge-commons paths reference
(docs/reference/fs/paths.md).
Context
Apollo does not wait for it; it keeps its helpers on today's pins and adopts these after release and a pin bump. Only the generic parts of its code move: the step that writes tags through a third-party library is specific to that library and stays in the application.
Design
The three operations sit on PathUtils in fs/paths.py, next to
atomic_write, which is rebuilt on atomic_replace so the kit has one
durable-publish path with its contract and tests unchanged. move_no_clobber
publishes with a hard link rather than a rename, so nothing that appears at the
destination between a check and the move is overwritten. prune_empty_parents
uses rmdir, never a recursive delete. Prior art is Apollo's filesystem
mutation module.
S17.5.1 — Build atomic_replace
State: Closed (2026-10-31)
Acceptance: PathUtils.atomic_replace behaves as under Design and its
tests pass.
S17.5.2 — Build move_no_clobber
State: Closed (2026-10-31)
Acceptance: PathUtils.move_no_clobber behaves as under Design and its
tests pass.
S17.5.3 — Build prune_empty_parents
State: Closed (2026-10-31)
Acceptance: PathUtils.prune_empty_parents behaves as under Design and
its tests pass.
Acceptance
set -euo pipefail
cd packages/rn-forge-commons
uv run pytest -q tests/fs/test_paths.py # S17.5.1 S17.5.2 S17.5.3
uv run pyright && uv run lint-imports # S17.5.1 S17.5.2 S17.5.3
uv run --group docs mkdocs build --strict # S17.5.1 S17.5.2 S17.5.3
Considered and rejected
exists()thenPath.replace, as Apollo does. The rename overwrites anything created between the check and the move.- An
O_EXCLfallback for filesystems without hard links. It reserves the name but leaves a partly written destination visible while the copy runs. - Extending
atomic_writewith a callback. Its contract is content in, file out; an edit that needs a file path does not fit it. Process.tool_version. Its version parsing carries Apollo's fallbacks, and one application probes tools; it is parked in the ideas list.- A recursive prune. Removing anything but an empty directory is how a
library gets deleted;
rmdirfails safely instead.