aiocortex 0.1.0__tar.gz

aiocortex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cortex 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.

aiocortex-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: aiocortex
+Version: 0.1.0
+Summary: Async Python library for Home Assistant configuration management
+Author: Cortex Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ruaan-deysel/aiocortex
+Project-URL: Repository, https://github.com/ruaan-deysel/aiocortex
+Project-URL: Issues, https://github.com/ruaan-deysel/aiocortex/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: dulwich>=0.22.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: types-aiofiles>=23.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+# aiocortex
+
+Async Python library for Home Assistant configuration management. Provides git versioning (via dulwich), file management, YAML editing, and Pydantic models — all independent of Home Assistant internals.
+
+This library is the core engine behind the [Cortex](https://github.com/ruaan-deysel/ha-cortex) HACS integration.
+
+## Installation
+
+```bash
+pip install aiocortex
+```
+
+## Features
+
+- **Git versioning** — Shadow git repository for HA config backups using [dulwich](https://www.dulwich.io/) (pure Python, no git binary required)
+- **File management** — Async file operations with path security (directory traversal prevention)
+- **YAML editing** — Safe YAML read/write/parse utilities
+- **Pydantic models** — Typed data models for automations, scripts, helpers, files, git commits
+
+## Quick Start
+
+```python
+from aiocortex import AsyncFileManager, GitManager, YAMLEditor
+
+# File operations
+file_mgr = AsyncFileManager(config_path=Path("/config"))
+files = await file_mgr.list_files("", "*.yaml")
+content = await file_mgr.read_file("automations.yaml")
+
+# Git versioning
+git_mgr = GitManager(config_path=Path("/config"), max_backups=30)
+await git_mgr.init_repo()
+await git_mgr.commit_changes("Add automation: motion sensor light")
+history = await git_mgr.get_history(limit=10)
+
+# YAML editing
+editor = YAMLEditor()
+result = editor.remove_yaml_entry(content, "- id: 'old_automation'")
+```
+
+## Architecture
+
+```
+aiocortex/
+├── git/           # GitManager, sync, filters, cleanup (dulwich-based)
+├── files/         # AsyncFileManager, YAMLEditor
+├── models/        # Pydantic v2 models (common, config, files, git)
+└── exceptions.py  # CortexError hierarchy
+```
+
+### Design Principle
+
+If it imports `homeassistant.*`, it does **not** belong here. This library contains only HA-independent logic. The Cortex integration handles all HA-specific concerns (states, services, registries, auth, HTTP routing).
+
+## Models
+
+```python
+from aiocortex.models import (
+    AutomationConfig,   # Automation definition
+    ScriptConfig,       # Script definition
+    HelperSpec,         # Input helper specification
+    ServiceCallSpec,    # Service call parameters
+    FileInfo,           # File metadata
+    FileWriteResult,    # Write operation result
+    CommitInfo,         # Git commit metadata
+    PendingChanges,     # Uncommitted changes
+    CortexResponse,     # Standard API response
+)
+```
+
+## Dependencies
+
+- `pydantic>=2.0` — Data validation and models
+- `pyyaml>=6.0` — YAML parsing
+- `aiofiles>=23.0` — Async file I/O
+- `dulwich>=0.22.0` — Pure Python git implementation
+
+## Development
+
+```bash
+git clone https://github.com/ruaan-deysel/aiocortex.git
+cd aiocortex
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest --cov=aiocortex
+```
+
+## License
+
+MIT

aiocortex-0.1.0/README.md

@@ -0,0 +1,90 @@
+# aiocortex
+
+Async Python library for Home Assistant configuration management. Provides git versioning (via dulwich), file management, YAML editing, and Pydantic models — all independent of Home Assistant internals.
+
+This library is the core engine behind the [Cortex](https://github.com/ruaan-deysel/ha-cortex) HACS integration.
+
+## Installation
+
+```bash
+pip install aiocortex
+```
+
+## Features
+
+- **Git versioning** — Shadow git repository for HA config backups using [dulwich](https://www.dulwich.io/) (pure Python, no git binary required)
+- **File management** — Async file operations with path security (directory traversal prevention)
+- **YAML editing** — Safe YAML read/write/parse utilities
+- **Pydantic models** — Typed data models for automations, scripts, helpers, files, git commits
+
+## Quick Start
+
+```python
+from aiocortex import AsyncFileManager, GitManager, YAMLEditor
+
+# File operations
+file_mgr = AsyncFileManager(config_path=Path("/config"))
+files = await file_mgr.list_files("", "*.yaml")
+content = await file_mgr.read_file("automations.yaml")
+
+# Git versioning
+git_mgr = GitManager(config_path=Path("/config"), max_backups=30)
+await git_mgr.init_repo()
+await git_mgr.commit_changes("Add automation: motion sensor light")
+history = await git_mgr.get_history(limit=10)
+
+# YAML editing
+editor = YAMLEditor()
+result = editor.remove_yaml_entry(content, "- id: 'old_automation'")
+```
+
+## Architecture
+
+```
+aiocortex/
+├── git/           # GitManager, sync, filters, cleanup (dulwich-based)
+├── files/         # AsyncFileManager, YAMLEditor
+├── models/        # Pydantic v2 models (common, config, files, git)
+└── exceptions.py  # CortexError hierarchy
+```
+
+### Design Principle
+
+If it imports `homeassistant.*`, it does **not** belong here. This library contains only HA-independent logic. The Cortex integration handles all HA-specific concerns (states, services, registries, auth, HTTP routing).
+
+## Models
+
+```python
+from aiocortex.models import (
+    AutomationConfig,   # Automation definition
+    ScriptConfig,       # Script definition
+    HelperSpec,         # Input helper specification
+    ServiceCallSpec,    # Service call parameters
+    FileInfo,           # File metadata
+    FileWriteResult,    # Write operation result
+    CommitInfo,         # Git commit metadata
+    PendingChanges,     # Uncommitted changes
+    CortexResponse,     # Standard API response
+)
+```
+
+## Dependencies
+
+- `pydantic>=2.0` — Data validation and models
+- `pyyaml>=6.0` — YAML parsing
+- `aiofiles>=23.0` — Async file I/O
+- `dulwich>=0.22.0` — Pure Python git implementation
+
+## Development
+
+```bash
+git clone https://github.com/ruaan-deysel/aiocortex.git
+cd aiocortex
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest --cov=aiocortex
+```
+
+## License
+
+MIT

aiocortex-0.1.0/pyproject.toml

@@ -0,0 +1,123 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiocortex"
+version = "0.1.0"
+description = "Async Python library for Home Assistant configuration management"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    {name = "Cortex Contributors"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "pydantic>=2.0,<3.0",
+    "pyyaml>=6.0",
+    "aiofiles>=23.0",
+    "dulwich>=0.22.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ruaan-deysel/aiocortex"
+Repository = "https://github.com/ruaan-deysel/aiocortex"
+Issues = "https://github.com/ruaan-deysel/aiocortex/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.1.0",
+    "types-aiofiles>=23.0",
+    "types-PyYAML>=6.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiocortex = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+required-version = ">=0.15.1"
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = [
+  "A001",   # Variable shadowing a Python builtin
+  "ASYNC",  # flake8-async
+  "B",      # flake8-bugbear
+  "BLE",    # flake8-blind-except
+  "C",      # complexity
+  "E",      # pycodestyle
+  "F",      # pyflakes
+  "FLY",    # flynt
+  "G",      # flake8-logging-format
+  "I",      # isort
+  "ICN001", # import conventions
+  "LOG",    # flake8-logging
+  "N804",   # First argument of a class method should be named cls
+  "N805",   # First argument of a method should be named self
+  "PERF",   # perflint
+  "PGH",    # pygrep-hooks
+  "PIE",    # flake8-pie
+  "PL",     # pylint
+  "PT",     # flake8-pytest-style
+  "RET",    # flake8-return
+  "RSE",    # flake8-raise
+  "RUF",    # ruff-specific rules
+  "T20",    # flake8-print
+  "UP",     # pyupgrade
+  "W",      # pycodestyle warnings
+]
+ignore = [
+  "BLE001",  # Blind exception catch — intentional in cleanup/fallback code
+  "C901",    # Too complex — ported code, complexity is inherent
+  "PLC0415", # Import not at top-level — intentional lazy imports
+  "PERF401", # Use list comprehension — clarity preferred in some cases
+  "PLR0911", # Too many return statements
+  "PLR0912", # Too many branches
+  "PLR0913", # Too many arguments
+  "PLR0915", # Too many statements
+  "PLR2004", # Magic value comparison
+  "PLW1510", # subprocess.run without check — we check return codes manually
+  "RET504",  # Unnecessary assignment before return
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiocortex"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "PLR2004", "PT", "F841"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["dulwich.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["aiocortex.git.*"]
+disallow_any_expr = false
+warn_return_any = false
+disable_error_code = ["attr-defined", "arg-type", "assignment", "union-attr"]

aiocortex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiocortex-0.1.0/src/aiocortex/__init__.py

@@ -0,0 +1,48 @@
+"""aiocortex — Async Python library for Home Assistant configuration management."""
+
+from ._version import __version__
+from .exceptions import (
+    CortexError,
+    FileError,
+    GitError,
+    GitNotInitializedError,
+    PathSecurityError,
+    YAMLParseError,
+)
+from .files import AsyncFileManager, YAMLEditor
+from .git import GitManager
+from .models import (
+    AutomationConfig,
+    CommitInfo,
+    CortexResponse,
+    FileInfo,
+    FileWriteResult,
+    HelperSpec,
+    PendingChanges,
+    PendingChangesSummary,
+    ScriptConfig,
+    ServiceCallSpec,
+)
+
+__all__ = [
+    "AsyncFileManager",
+    "AutomationConfig",
+    "CommitInfo",
+    "CortexError",
+    "CortexResponse",
+    "FileError",
+    "FileInfo",
+    "FileWriteResult",
+    "GitError",
+    "GitManager",
+    "GitNotInitializedError",
+    "HelperSpec",
+    "PathSecurityError",
+    "PendingChanges",
+    "PendingChangesSummary",
+    "ScriptConfig",
+    "ServiceCallSpec",
+    "YAMLEditor",
+    "YAMLParseError",
+    "__version__",
+]

aiocortex-0.1.0/src/aiocortex/_version.py

@@ -0,0 +1,3 @@
+"""Version information."""
+
+__version__ = "0.1.0"

aiocortex-0.1.0/src/aiocortex/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception hierarchy for aiocortex."""
+
+
+class CortexError(Exception):
+    """Base exception for all aiocortex errors."""
+
+
+class GitError(CortexError):
+    """Error during a git operation."""
+
+
+class GitNotInitializedError(GitError):
+    """The shadow git repository has not been initialized."""
+
+
+class FileError(CortexError):
+    """Error during a file operation."""
+
+
+class PathSecurityError(FileError):
+    """A requested path resolved outside the allowed config directory."""
+
+
+class YAMLParseError(FileError):
+    """Failed to parse a YAML file."""

aiocortex-0.1.0/src/aiocortex/files/__init__.py

@@ -0,0 +1,6 @@
+"""File management utilities."""
+
+from .manager import AsyncFileManager
+from .yaml_editor import YAMLEditor
+
+__all__ = ["AsyncFileManager", "YAMLEditor"]

aiocortex-0.1.0/src/aiocortex/files/manager.py

@@ -0,0 +1,196 @@
+"""Async file manager for Home Assistant configuration files.
+
+Ported from ``app/services/file_manager.py`` in the HA Vibecode Agent add-on.
+This version is *HA-independent*: it receives ``config_path`` via its
+constructor and never imports git — the integration layer is responsible for
+orchestrating git commits after file operations.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import aiofiles
+import yaml
+
+from ..exceptions import FileError, PathSecurityError, YAMLParseError
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncFileManager:
+    """Safe async file operations restricted to a *config_path* directory."""
+
+    def __init__(self, config_path: Path) -> None:
+        self.config_path = config_path.resolve()
+
+    # ------------------------------------------------------------------
+    # Path helpers
+    # ------------------------------------------------------------------
+
+    def _get_full_path(self, relative_path: str) -> Path:
+        """Return the absolute path, ensuring it stays within *config_path*.
+
+        Raises :class:`PathSecurityError` if the resolved path escapes the
+        allowed directory tree.
+        """
+        if relative_path in ("", "/"):
+            return self.config_path
+
+        # Strip leading slash — treat as relative
+        if relative_path.startswith("/"):
+            relative_path = relative_path[1:]
+
+        full_path = (self.config_path / relative_path).resolve()
+
+        if not str(full_path).startswith(str(self.config_path)):
+            raise PathSecurityError(f"Path outside config directory: {relative_path}")
+
+        return full_path
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def list_files(
+        self,
+        directory: str = "",
+        pattern: str = "*",
+    ) -> list[dict[str, object]]:
+        """List files in *directory* matching *pattern* (recursive glob)."""
+        try:
+            dir_path = self._get_full_path(directory)
+
+            if not dir_path.exists():
+                return []
+
+            files: list[dict[str, object]] = []
+            for item in dir_path.rglob(pattern):
+                if item.is_file():
+                    rel_path = item.relative_to(self.config_path)
+                    stat = item.stat()
+                    files.append(
+                        {
+                            "path": str(rel_path),
+                            "name": item.name,
+                            "size": stat.st_size,
+                            "modified": stat.st_mtime,
+                            "is_yaml": item.suffix in (".yaml", ".yml"),
+                        }
+                    )
+
+            return sorted(files, key=lambda x: str(x["path"]))
+        except PathSecurityError:
+            raise
+        except Exception as exc:
+            logger.error("Error listing files: %s", exc)
+            raise FileError(str(exc)) from exc
+
+    async def read_file(self, file_path: str) -> str:
+        """Read and return the UTF-8 contents of *file_path*."""
+        try:
+            full_path = self._get_full_path(file_path)
+
+            if not full_path.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            async with aiofiles.open(full_path, encoding="utf-8") as fh:
+                content = await fh.read()
+
+            logger.info("Read file: %s (%d bytes)", file_path, len(content))
+            return content
+        except (FileNotFoundError, PathSecurityError):
+            raise
+        except Exception as exc:
+            logger.error("Error reading file %s: %s", file_path, exc)
+            raise FileError(str(exc)) from exc
+
+    async def write_file(self, file_path: str, content: str) -> dict[str, object]:
+        """Write *content* to *file_path*, creating parent directories as needed.
+
+        Returns a result dict with *success*, *path*, and *size*.
+
+        .. note::
+
+            This method does **not** interact with git.  The integration layer
+            should call ``GitManager.commit_changes()`` afterwards if desired.
+        """
+        try:
+            full_path = self._get_full_path(file_path)
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+
+            async with aiofiles.open(full_path, "w", encoding="utf-8") as fh:
+                await fh.write(content)
+
+            logger.info("Wrote file: %s (%d bytes)", file_path, len(content))
+
+            return {"success": True, "path": file_path, "size": len(content)}
+        except PathSecurityError:
+            raise
+        except Exception as exc:
+            logger.error("Error writing file %s: %s", file_path, exc)
+            raise FileError(str(exc)) from exc
+
+    async def append_file(self, file_path: str, content: str) -> dict[str, object]:
+        """Append *content* to *file_path*, creating it if it doesn't exist."""
+        try:
+            full_path = self._get_full_path(file_path)
+
+            if not full_path.exists():
+                full_path.parent.mkdir(parents=True, exist_ok=True)
+                full_path.touch()
+
+            async with aiofiles.open(full_path, encoding="utf-8") as fh:
+                existing = await fh.read()
+
+            new_content = (existing + "\n" + content) if existing else content
+
+            async with aiofiles.open(full_path, "w", encoding="utf-8") as fh:
+                await fh.write(new_content)
+
+            logger.info("Appended to file: %s (%d bytes)", file_path, len(content))
+
+            return {
+                "success": True,
+                "path": file_path,
+                "added_bytes": len(content),
+                "total_size": len(new_content),
+            }
+        except PathSecurityError:
+            raise
+        except Exception as exc:
+            logger.error("Error appending to file %s: %s", file_path, exc)
+            raise FileError(str(exc)) from exc
+
+    async def delete_file(self, file_path: str) -> dict[str, object]:
+        """Delete *file_path*.
+
+        Returns a result dict with *success* and *path*.
+        """
+        try:
+            full_path = self._get_full_path(file_path)
+
+            if not full_path.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            full_path.unlink()
+            logger.info("Deleted file: %s", file_path)
+
+            return {"success": True, "path": file_path}
+        except (FileNotFoundError, PathSecurityError):
+            raise
+        except Exception as exc:
+            logger.error("Error deleting file %s: %s", file_path, exc)
+            raise FileError(str(exc)) from exc
+
+    async def parse_yaml(self, file_path: str) -> dict[str, Any]:
+        """Parse a YAML file and return its contents as a dict."""
+        try:
+            content = await self.read_file(file_path)
+            data = yaml.safe_load(content)
+            return data or {}
+        except yaml.YAMLError as exc:
+            logger.error("YAML parse error in %s: %s", file_path, exc)
+            raise YAMLParseError(f"Invalid YAML: {exc}") from exc