Skip to content

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() then Path.replace, as Apollo does. The rename overwrites anything created between the check and the move.
  • An O_EXCL fallback for filesystems without hard links. It reserves the name but leaves a partly written destination visible while the copy runs.
  • Extending atomic_write with 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; rmdir fails safely instead.