axm-edit 0.4.0

axm-edit — Validated batch file editing for AXM agents and Python callers

batch_edit replaces, creates, deletes and rewrites files in one request. It validates before writing and snapshots the target paths for automatic rollback on apply failure. Apply and recovery are best-effort filesystem operations, not an OS transaction or a lock against concurrent writers.

Features

• Whole-line replacement, file creation, deletion and checksum-guarded rewrite.
• Batch validation before writing and targeted snapshots for recovery.
• Read-only batch checks and file inspection, search and listing tools.
• Python API and registered tools for the unified AXM CLI and MCP server.

Installation

uv add axm-edit
uv run axm batch_edit --help

Python 3.12+ is required. The dependency axm supplies the generic CLI; there is no separate axm-edit executable. Install axm-mcp in the same environment to expose the registered axm.tools to an MCP client.

Quick Start

This self-contained Python example changes only a temporary directory. The root API does not run the tool's preflight or post-edit Ruff pass. Save it as example.py and run uv run python example.py after installation.

from pathlib import Path
from tempfile import TemporaryDirectory

from axm_edit import CreateOp, Edit, ReplaceOp, batch_apply, rollback

with TemporaryDirectory() as directory:
    root = Path(directory)
    (root / "settings.txt").write_text("mode = draft\n", encoding="utf-8")
    result = batch_apply(root, [
        ReplaceOp(file="settings.txt", edits=[
            Edit(old="mode = draft", new="mode = ready"),
        ]),
        CreateOp(file="notes.txt", content="Ready for review.\n"),
    ])
    assert result.success, result.error
    assert result.summary == {"modified": 1, "created": 1, "deleted": 0}
    assert result.checkpoint is not None
    restored = rollback(root, result.checkpoint)
    assert restored.ok, restored.unrestored
    assert (root / "settings.txt").read_text() == "mode = draft\n"
    assert not (root / "notes.txt").exists()

The assertions verify that one file was changed and another created, then that rollback restored their prior state. Success produces no output.

Usage

Choose an interface

read_file, write_file and edit_file take path (project root) and file (target within it). file_bytes instead takes a file path without project-root confinement. run_command constrains its initial working directory, not the executable's filesystem or network access.

The tool batch_edit runs Ruff fix/format by default on touched Python files; use lint=False / CLI --no-lint to apply only the supplied edits. A successful tool result does not certify lint cleanliness. The checkpoint is present in structured data after apply starts, but is omitted from the compact text returned by the MCP axm_call façade.

Documentation

• Getting started
• Batch contracts
• Filesystem tools
• Rollback and concurrency limits
• Python API

Development

From the axm-forge workspace root:

uv sync --all-packages --all-groups
uv run --package axm-edit --directory packages/axm-edit pytest
uv run --package axm-edit --directory packages/axm-edit --group docs mkdocs build --strict

See CONTRIBUTING.md for the workspace workflow. The MkDocs homepage is docs/index.md; this README is a separate entry point.

License

Licensed under Apache-2.0. See LICENSE.