axio-tools-local 0.1.0__tar.gz

axio_tools_local-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Set version from release tag
+        run: uv version "${GITHUB_REF_NAME#v}"
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

axio_tools_local-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: tests
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run mypy .
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python:
+          - "3.12"
+          - "3.13"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen
+      - run: uv run pytest -vv --cov=axio_tools_local --cov-report=term-missing

axio_tools_local-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Axio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axio_tools_local-0.1.0/Makefile

@@ -0,0 +1,16 @@
+.PHONY: fmt lint typecheck test all
+
+fmt:
+	uv run ruff format src/ tests/
+	uv run ruff check --fix src/ tests/
+
+lint:
+	uv run ruff check src/ tests/
+
+typecheck:
+	uv run mypy src/
+
+test:
+	uv run pytest tests/ -v
+
+all: fmt lint typecheck test

axio_tools_local-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: axio-tools-local
+Version: 0.1.0
+Summary: Core filesystem and execution tools for Axio
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: axio

axio_tools_local-0.1.0/README.md

@@ -0,0 +1,15 @@
+# axio-tools-local
+
+Core filesystem and execution tools for Axio.
+
+Part of the [axio-agent](https://github.com/axio-agent) ecosystem.
+
+## Installation
+
+```bash
+pip install axio-tools-local
+```
+
+## License
+
+MIT

axio_tools_local-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "axio-tools-local"
+version = "0.1.0"
+description = "Core filesystem and execution tools for Axio"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+dependencies = ["axio"]
+
+[project.entry-points."axio.tools"]
+shell = "axio_tools_local.shell:Shell"
+run_python = "axio_tools_local.run_python:RunPython"
+write_file = "axio_tools_local.write_file:WriteFile"
+patch_file = "axio_tools_local.patch_file:PatchFile"
+read_file = "axio_tools_local.read_file:ReadFile"
+list_files = "axio_tools_local.list_files:ListFiles"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/axio_tools_local"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 119
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.14", "ruff>=0.9"]

axio_tools_local-0.1.0/src/axio_tools_local/__init__.py

@@ -0,0 +1,6 @@
+from typing import Any
+
+
+def _short(value: Any, limit: int = 60) -> str:
+    s = str(value)
+    return s if len(s) <= limit else s[:limit] + "..."

axio_tools_local-0.1.0/src/axio_tools_local/list_files.py

@@ -0,0 +1,36 @@
+import asyncio
+import os
+import stat as stat_module
+from datetime import datetime
+from pathlib import Path
+
+from axio.tool import ToolHandler
+
+
+class ListFiles(ToolHandler):
+    """List files and directories. Shows permissions, size, modification time,
+    and name for each entry. Directories are listed first and marked with
+    a trailing slash. Use this to explore the project structure before
+    reading or editing files."""
+
+    directory: str = "."
+
+    def __repr__(self) -> str:
+        return f"ListFiles(directory={self.directory!r})"
+
+    def _blocking(self) -> str:
+        path = Path(os.getcwd()) / self.directory
+        if not path.is_dir():
+            raise FileNotFoundError(f"{self.directory} is not a valid directory")
+        lines: list[str] = []
+        for fpath in sorted(path.glob("*"), key=lambda p: (not p.is_dir(), p.name)):
+            st = fpath.stat()
+            mode = stat_module.filemode(st.st_mode)
+            size = st.st_size
+            mtime = datetime.fromtimestamp(st.st_mtime).strftime("%b %d %H:%M")
+            name = fpath.name + ("/" if fpath.is_dir() else "")
+            lines.append(f"{mode} {size:>8} {mtime} {name}")
+        return "\n".join(lines) or "(empty directory)"
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

axio_tools_local-0.1.0/src/axio_tools_local/patch_file.py

@@ -0,0 +1,46 @@
+import asyncio
+import os
+from pathlib import Path
+
+from axio.tool import ToolHandler
+
+
+class PatchFile(ToolHandler):
+    """Replace a range of lines in an existing file. Lines are 0-indexed:
+    from_line is inclusive, to_line is exclusive. The content string replaces
+    lines[from_line:to_line]. Always read the file first to get correct
+    line numbers. Use this for surgical edits instead of rewriting the
+    whole file with write_file."""
+
+    file_path: str
+    mode: int = 0o644
+    from_line: int
+    to_line: int
+    content: str
+
+    def __repr__(self) -> str:
+        return (
+            f"PatchFile(file_path={self.file_path!r},"
+            f" lines={self.from_line}:{self.to_line}, content=<{len(self.content)} chars>)"
+        )
+
+    def _blocking(self) -> str:
+        path = Path(os.getcwd()) / self.file_path
+        if not path.is_file():
+            raise FileNotFoundError(f"{self.file_path} is not a valid file")
+
+        # read all lines
+        with path.open("r") as f:
+            lines = f.readlines()
+
+        # content lines
+        content = self.content.splitlines()
+
+        # patch lines
+        new_lines = lines[: self.from_line] + content + lines[self.to_line :]
+        with path.open("w") as f:
+            f.writelines(new_lines)
+            return f"{f.tell()} bytes written to {self.file_path}"
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

axio_tools_local-0.1.0/src/axio_tools_local/read_file.py

@@ -0,0 +1,41 @@
+import asyncio
+import os
+
+from axio.tool import ToolHandler
+
+
+class ReadFile(ToolHandler):
+    """Read file contents. Returns text for text files, hex for binaries.
+    Use start_line/end_line to read a specific range of lines (0-indexed).
+    Large files are truncated to max_chars. Always read the file before
+    editing it with write_file or patch_file."""
+
+    filename: str
+    max_chars: int = 32768
+    binary_as_hex: bool = True
+    start_line: int | None = None
+    end_line: int | None = None
+
+    def __repr__(self) -> str:
+        return f"ReadFile(filename={self.filename!r})"
+
+    def _blocking(self) -> str:
+        path = os.path.join(os.getcwd(), self.filename)
+        if self.start_line is None and self.end_line is None:
+            with open(path, "rb") as f:
+                result = f.read(self.max_chars)
+            try:
+                return result.decode()
+            except UnicodeDecodeError:
+                if self.binary_as_hex:
+                    return "Encoded binary data HEX: " + result.hex()
+                raise
+        with open(path) as f:
+            lines = f.readlines()[self.start_line : self.end_line]
+            content = "".join(lines)
+            if len(content) > self.max_chars:
+                return content[: self.max_chars] + "\n...[truncated]"
+            return content.strip()
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

axio_tools_local-0.1.0/src/axio_tools_local/run_python.py

@@ -0,0 +1,56 @@
+import asyncio
+import os
+import subprocess
+import sys
+import tempfile
+
+from axio.tool import ToolHandler
+
+from . import _short
+
+
+class RunPython(ToolHandler):
+    """Run a Python code snippet in a subprocess and return stdout/stderr.
+    The code is written to a temp file and executed with the current
+    interpreter. Use for calculations, data processing, or testing
+    small scripts. Optionally pass stdin data. Non-zero exit codes
+    and tracebacks are returned as-is."""
+
+    code: str
+    cwd: str = "."
+    timeout: int = 5
+    stdin: str | None = None
+
+    def __repr__(self) -> str:
+        return f"RunPython(code={_short(self.code)!r}, cwd={self.cwd!r})"
+
+    def _blocking(self) -> str:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py") as f:
+            f.write(self.code)
+            f.flush()
+
+            path = f.name
+
+            try:
+                result = subprocess.run(
+                    [sys.executable, path],
+                    capture_output=True,
+                    text=True,
+                    timeout=self.timeout,
+                    cwd=self.cwd,
+                    input=self.stdin if self.stdin is not None else None,
+                    stdin=subprocess.DEVNULL if self.stdin is None else None,
+                )
+                output = ""
+                if result.stdout:
+                    output += result.stdout
+                if result.stderr:
+                    output += f"\n[stderr]\n{result.stderr}"
+                if result.returncode != 0:
+                    output += f"\n[exit code: {result.returncode}]"
+                return output.strip() or "(no output)"
+            finally:
+                os.unlink(path)
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

axio_tools_local-0.1.0/src/axio_tools_local/shell.py

@@ -0,0 +1,44 @@
+import asyncio
+import subprocess
+
+from axio.tool import ToolHandler
+
+from . import _short
+
+
+class Shell(ToolHandler):
+    """Run a shell command and return combined stdout/stderr. Use for git,
+    build tools, grep, tests, or any CLI operation. Non-zero exit codes
+    are reported. Optionally pass stdin data for commands that read from
+    standard input. Prefer short timeouts and avoid interactive commands."""
+
+    command: str
+    timeout: int = 5
+    cwd: str = "."
+    stdin: str | None = None
+
+    def __repr__(self) -> str:
+        return f"Shell(command={_short(self.command)!r}, cwd={self.cwd!r})"
+
+    def _blocking(self) -> str:
+        result = subprocess.run(
+            self.command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=self.timeout,
+            cwd=self.cwd,
+            input=self.stdin if self.stdin is not None else None,
+            stdin=subprocess.DEVNULL if self.stdin is None else None,
+        )
+        output = ""
+        if result.stdout:
+            output += result.stdout
+        if result.stderr:
+            output += f"\n[stderr]\n{result.stderr}"
+        if result.returncode != 0:
+            output += f"\n[exit code: {result.returncode}]"
+        return output.strip() or "(no output)"
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

axio_tools_local-0.1.0/src/axio_tools_local/write_file.py

@@ -0,0 +1,28 @@
+import asyncio
+import os
+
+from axio.tool import ToolHandler
+
+
+class WriteFile(ToolHandler):
+    """Create or overwrite a file with the given content. Parent directories
+    are created automatically. Use this for new files or full rewrites.
+    For partial edits prefer patch_file instead."""
+
+    file_path: str
+    content: str
+    mode: int = 0o644
+
+    def __repr__(self) -> str:
+        return f"WriteFile(file_path={self.file_path!r}, content=<{len(self.content)} chars>)"
+
+    def _blocking(self) -> str:
+        path = os.path.join(os.getcwd(), self.file_path)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as f:
+            f.write(self.content)
+        os.chmod(path, mode=self.mode)
+        return f"Wrote {len(self.content)} bytes to {self.file_path}"
+
+    async def __call__(self) -> str:
+        return await asyncio.to_thread(self._blocking)

axio_tools_local-0.1.0/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared test fixtures for axio-tools-local."""

axio_tools_local-0.1.0/tests/test_list_files.py

@@ -0,0 +1,62 @@
+"""Tests for ListFiles tool handler."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from axio_tools_local.list_files import ListFiles
+
+
+class TestListFiles:
+    async def test_list_directory(self, tmp_path: Path) -> None:
+        (tmp_path / "a.txt").write_text("a")
+        (tmp_path / "b.txt").write_text("b")
+        (tmp_path / "subdir").mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ListFiles(directory=".")
+            result = await handler()
+            assert "a.txt" in result
+            assert "b.txt" in result
+            assert "subdir/" in result
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_empty_directory(self, tmp_path: Path) -> None:
+        empty = tmp_path / "empty"
+        empty.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ListFiles(directory="empty")
+            result = await handler()
+            assert result == "(empty directory)"
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_default_directory(self, tmp_path: Path) -> None:
+        (tmp_path / "file.txt").write_text("x")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ListFiles()
+            assert handler.directory == "."
+            result = await handler()
+            assert "file.txt" in result
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_not_a_directory(self, tmp_path: Path) -> None:
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ListFiles(directory="nope")
+            try:
+                await handler()
+                assert False, "Should have raised"
+            except FileNotFoundError:
+                pass
+        finally:
+            os.chdir(old_cwd)

axio_tools_local-0.1.0/tests/test_patch_file.py

@@ -0,0 +1,45 @@
+"""Tests for PatchFile tool handler."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from axio_tools_local.patch_file import PatchFile
+
+
+class TestPatchFile:
+    async def test_patch_lines(self, tmp_path: Path) -> None:
+        target = tmp_path / "file.txt"
+        target.write_text("line0\nline1\nline2\nline3\n")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = PatchFile(file_path="file.txt", from_line=1, to_line=3, content="replaced\n")
+            result = await handler()
+            assert "bytes written" in result
+            content = target.read_text()
+            assert "replaced" in content
+            assert "line1" not in content
+            assert "line2" not in content
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_file_not_found(self, tmp_path: Path) -> None:
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = PatchFile(file_path="missing.txt", from_line=0, to_line=1, content="x")
+            try:
+                await handler()
+                assert False, "Should have raised"
+            except FileNotFoundError:
+                pass
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_repr(self) -> None:
+        handler = PatchFile(file_path="f.py", from_line=5, to_line=10, content="code")
+        r = repr(handler)
+        assert "f.py" in r
+        assert "5:10" in r

axio_tools_local-0.1.0/tests/test_read_file.py

@@ -0,0 +1,49 @@
+"""Tests for ReadFile tool handler."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from axio_tools_local.read_file import ReadFile
+
+
+class TestReadFile:
+    async def test_read_text(self, tmp_path: Path) -> None:
+        (tmp_path / "hello.txt").write_text("content here")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ReadFile(filename="hello.txt")
+            result = await handler()
+            assert result == "content here"
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_read_binary_as_hex(self, tmp_path: Path) -> None:
+        (tmp_path / "bin.dat").write_bytes(b"\x80\x81\xff")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ReadFile(filename="bin.dat", binary_as_hex=True)
+            result = await handler()
+            assert "8081ff" in result
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_file_not_found(self, tmp_path: Path) -> None:
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = ReadFile(filename="nope.txt")
+            try:
+                await handler()
+                assert False, "Should have raised"
+            except FileNotFoundError:
+                pass
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_repr(self) -> None:
+        handler = ReadFile(filename="test.py")
+        assert "test.py" in repr(handler)

axio_tools_local-0.1.0/tests/test_run_python.py

@@ -0,0 +1,38 @@
+"""Tests for RunPython tool handler."""
+
+from __future__ import annotations
+
+from axio_tools_local.run_python import RunPython
+
+
+class TestRunPython:
+    async def test_simple_print(self) -> None:
+        handler = RunPython(code="print('hello')", timeout=5)
+        result = await handler()
+        assert "hello" in result
+
+    async def test_error(self) -> None:
+        handler = RunPython(code="raise ValueError('boom')", timeout=5)
+        result = await handler()
+        assert "ValueError" in result
+        assert "exit code:" in result
+
+    async def test_stdin_devnull(self) -> None:
+        """stdin must be /dev/null so subprocesses can't steal TUI key events."""
+        handler = RunPython(code="import sys; data = sys.stdin.read(); print(repr(data))", timeout=2)
+        result = await handler()
+        # stdin is /dev/null → immediate EOF → empty string
+        assert "''" in result
+
+    async def test_stdin_passthrough(self) -> None:
+        handler = RunPython(
+            code="import sys; print(sys.stdin.read())",
+            timeout=5,
+            stdin="hello from stdin",
+        )
+        result = await handler()
+        assert "hello from stdin" in result
+
+    async def test_repr(self) -> None:
+        handler = RunPython(code="x = 1")
+        assert "x = 1" in repr(handler)

axio_tools_local-0.1.0/tests/test_shell.py

@@ -0,0 +1,45 @@
+"""Tests for Shell tool handler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from axio_tools_local.shell import Shell
+
+
+class TestShell:
+    async def test_echo(self) -> None:
+        handler = Shell(command="echo hello", timeout=5)
+        result = await handler()
+        assert "hello" in result
+
+    async def test_stderr(self) -> None:
+        handler = Shell(command="echo err >&2", timeout=5)
+        result = await handler()
+        assert "err" in result
+
+    async def test_nonzero_exit(self) -> None:
+        handler = Shell(command="exit 42", timeout=5)
+        result = await handler()
+        assert "exit code: 42" in result
+
+    async def test_cwd(self, tmp_path: Path) -> None:
+        handler = Shell(command="pwd", timeout=5, cwd=str(tmp_path))
+        result = await handler()
+        assert str(tmp_path) in result
+
+    async def test_stdin_devnull(self) -> None:
+        """stdin must be /dev/null so subprocesses can't steal TUI key events."""
+        handler = Shell(command="cat", timeout=2)
+        result = await handler()
+        # cat with no args + /dev/null stdin → immediate EOF → "(no output)"
+        assert result == "(no output)"
+
+    async def test_stdin_passthrough(self) -> None:
+        handler = Shell(command="cat", timeout=5, stdin="hello from stdin")
+        result = await handler()
+        assert "hello from stdin" in result
+
+    async def test_repr(self) -> None:
+        handler = Shell(command="echo hi")
+        assert "echo hi" in repr(handler)

axio_tools_local-0.1.0/tests/test_write_file.py

@@ -0,0 +1,37 @@
+"""Tests for WriteFile tool handler."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from axio_tools_local.write_file import WriteFile
+
+
+class TestWriteFile:
+    async def test_write_and_read_back(self, tmp_path: Path) -> None:
+        target = tmp_path / "out.txt"
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = WriteFile(file_path="out.txt", content="hello world")
+            result = await handler()
+            assert "11" in result  # 11 bytes
+            assert target.read_text() == "hello world"
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_creates_subdirectories(self, tmp_path: Path) -> None:
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            handler = WriteFile(file_path="sub/dir/file.txt", content="nested")
+            await handler()
+            assert (tmp_path / "sub" / "dir" / "file.txt").read_text() == "nested"
+        finally:
+            os.chdir(old_cwd)
+
+    async def test_repr(self) -> None:
+        handler = WriteFile(file_path="f.txt", content="abc")
+        assert "f.txt" in repr(handler)
+        assert "3 chars" in repr(handler)