Checkpoint

checkpoint

Targeted path snapshot and rollback for atomic batch edits.

Before applying a batch, :func:create_checkpoint captures — for every path the batch will touch — whether it existed and its original bytes. :func:rollback then restores exactly those paths and nothing else: modified files are rewritten with their original bytes, files that did not exist before are removed, and files that were deleted are recreated.

No git is involved: the snapshot is independent of the repository (it works in a non-git directory and never runs git checkout/clean/stash). The snapshot is serialized to a JSON string so it can ride on the existing BatchResult.checkpoint field and cross the MCP boundary unchanged.

create_checkpoint(root, operations)

Snapshot every path operations will touch, before they are applied.

For each operation's target path the snapshot records whether the file currently exists and, if so, its original bytes. The result is a JSON string keyed by resolved relative path, suitable for storage on BatchResult.checkpoint and for passing back to :func:rollback.

Parameters:

Name	Type	Description	Default
root	Path	Project root directory (all paths are relative to this).	required
operations	Sequence[Operation]	The batch about to be applied — replace, create and delete operations whose file attribute names the target.	required

Returns:

Type	Description
str	A JSON snapshot string. Always returned (never None) whenever
str	there are operations, in git and non-git directories alike.

Source code in packages/axm-edit/src/axm_edit/core/checkpoint.py

def create_checkpoint(root: Path, operations: Sequence[Operation]) -> str:
    """Snapshot every path *operations* will touch, before they are applied.

    For each operation's target path the snapshot records whether the file
    currently exists and, if so, its original bytes. The result is a JSON
    string keyed by resolved relative path, suitable for storage on
    ``BatchResult.checkpoint`` and for passing back to :func:`rollback`.

    Args:
        root: Project root directory (all paths are relative to this).
        operations: The batch about to be applied — replace, create and
            delete operations whose ``file`` attribute names the target.

    Returns:
        A JSON snapshot string. Always returned (never ``None``) whenever
        there are operations, in git and non-git directories alike.
    """
    root = root.resolve()
    entries: dict[str, str | None] = {}
    created_dirs: set[str] = set()
    for op in operations:
        target = _resolve_within(root, op.file)
        if target is None:
            continue
        # Key the dedup on the canonical resolved-within path, not the raw
        # spelling: "a.py" and "./a.py" name the same file and must collapse
        # to a single entry. The canonical key is also what rollback re-resolves.
        rel = target.relative_to(root).as_posix()
        if rel in entries:
            continue
        if target.is_file():
            entries[rel] = base64.b64encode(target.read_bytes()).decode("ascii")
        else:
            entries[rel] = None
            created_dirs |= _ancestors_to_create(root, target)
    return json.dumps(
        {
            "version": _SNAPSHOT_VERSION,
            "entries": entries,
            "created_dirs": sorted(created_dirs),
        }
    )

rollback(root, checkpoint)

Restore exactly the paths captured by checkpoint to their prior state.

Rollback is a strict inverse of the batch and best-effort: for each snapshotted path a file that existed is rewritten with its original bytes, a file that did not exist before is removed, and only the directories the batch itself created (recorded in the snapshot) are pruned — a pre-existing directory is never removed. Every captured path is attempted even if an earlier one fails, so a partial rollback is fully reported. No git command is run.

Parameters:

Name	Type	Description	Default
root	Path	Project root directory.	required
checkpoint	str	The JSON snapshot returned by :func:create_checkpoint.	required

Returns:

Name	Type	Description
A	RollbackResult	class:~axm_edit.models.operations.RollbackResult listing the
	RollbackResult	paths restored and those that could not be restored. RollbackResult.ok
	RollbackResult	is True only on a well-formed snapshot with no per-path failure;
	RollbackResult	a malformed snapshot yields valid=False.

Source code in packages/axm-edit/src/axm_edit/core/checkpoint.py

def rollback(root: Path, checkpoint: str) -> RollbackResult:
    """Restore exactly the paths captured by *checkpoint* to their prior state.

    Rollback is a *strict inverse* of the batch and best-effort: for each
    snapshotted path a file that existed is rewritten with its original bytes,
    a file that did not exist before is removed, and only the directories the
    batch itself created (recorded in the snapshot) are pruned — a
    pre-existing directory is never removed. Every captured path is attempted
    even if an earlier one fails, so a partial rollback is fully reported. No
    git command is run.

    Args:
        root: Project root directory.
        checkpoint: The JSON snapshot returned by :func:`create_checkpoint`.

    Returns:
        A :class:`~axm_edit.models.operations.RollbackResult` listing the
        paths restored and those that could not be restored. ``RollbackResult.ok``
        is ``True`` only on a well-formed snapshot with no per-path failure;
        a malformed snapshot yields ``valid=False``.
    """
    root = root.resolve()
    try:
        payload = json.loads(checkpoint)
        entries = payload["entries"]
    except (ValueError, TypeError, KeyError):
        return RollbackResult(valid=False)
    if not isinstance(entries, dict):
        return RollbackResult(valid=False)

    created_dirs = _read_created_dirs(payload)
    restored: list[str] = []
    unrestored: list[str] = []
    for rel, encoded in entries.items():
        target = _resolve_within(root, rel)
        if target is None:
            continue
        try:
            _restore_one(target, encoded, root, created_dirs)
            restored.append(rel)
        except OSError:
            unrestored.append(rel)
    return RollbackResult(restored=restored, unrestored=unrestored)

snapshot_paths(checkpoint)

Return the relative paths captured by checkpoint (best-effort).

Read-only and side-effect free: a malformed snapshot yields an empty list so informational callers degrade gracefully.

Source code in packages/axm-edit/src/axm_edit/core/checkpoint.py

def snapshot_paths(checkpoint: str) -> list[str]:
    """Return the relative paths captured by *checkpoint* (best-effort).

    Read-only and side-effect free: a malformed snapshot yields an empty
    list so informational callers degrade gracefully.
    """
    try:
        payload = json.loads(checkpoint)
        entries = payload["entries"]
    except (ValueError, TypeError, KeyError):
        return []
    if not isinstance(entries, dict):
        return []
    return list(entries)