mafw.scaffold.writer

Atomic, roll-back-safe writer for generated projects.

The writer renders a project into a temporary staging directory created on the same filesystem as the final destination, and only moves it into place once rendering has completed successfully. If anything fails — a rendering error, a permission problem, or an interruption — the staging directory is removed and any destination directory the writer created is deleted, leaving the filesystem in its exact pre-run state.

This guarantees two of the feature’s correctness properties: no partially generated project is ever left behind, and a non-empty destination is never touched.

Added in version 2.4.

Functions

write_atomically(spec, render)

Render a project into staging and atomically move it to the destination.
mafw.scaffold.writer._is_non_empty_dir(path: Path) → bool[source]

Return True if path exists, is a directory, and contains any entry.

Parameters:

path (Path) – The path to inspect.

Returns:

Whether the path is a non-empty directory.

Return type:

bool

mafw.scaffold.writer._rollback(staging_dir: Path, destination: Path, destination_existed: bool, created_parent: bool, staging_parent: Path) → None[source]

Undo any filesystem changes made during a failed generation.

Parameters:

  • staging_dir (Path) – The staging directory to remove.

  • destination (Path) – The final destination directory.

  • destination_existed (bool) – Whether the destination existed before this run.

  • created_parent (bool) – Whether this run created the destination’s parent.

  • staging_parent (Path) – The destination’s parent directory.

mafw.scaffold.writer.write_atomically(spec: ProjectSpec, render: Callable[[Path], None]) → Path[source]

Render a project into staging and atomically move it to the destination.

The render callable receives the staging directory and is expected to populate it with the full project tree. The staging directory is created next to the destination (same filesystem) so the final move is an atomic rename rather than a cross-device copy.

Parameters:

  • spec (mafw.scaffold.spec.ProjectSpec) – The validated project specification; spec.destination is the final project directory.

  • render (Callable[[Path], None]) – A callable that writes the project into the given staging dir.

Returns:

The absolute path to the generated project root.

Return type:

Path

Raises: