aiocortex 0.2.0__tar.gz → 0.3.0__tar.gz

{aiocortex-0.2.0/src/aiocortex.egg-info → aiocortex-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiocortex
-Version: 0.2.0
+Version: 0.3.0
 Summary: Async Python library for Home Assistant configuration management
 Author: Cortex Contributors
 License-Expression: MIT
@@ -47,8 +47,9 @@ pip install aiocortex
 
 - **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
+- **YAML editing** — Safe YAML read/write/parse utilities + semantic patch preview/apply helpers
 - **Pydantic models** — Typed data models for automations, scripts, helpers, files, git commits
+- **Transactions** — Durable plan/apply/abort flow with rollback metadata for multi-step config changes
 - **AI Instructions** — Bundled markdown instruction docs for AI-powered HA management (sync & async loaders)
 
 ## Quick Start
@@ -67,9 +68,23 @@ await git_mgr.init_repo()
 await git_mgr.commit_changes("Add automation: motion sensor light")
 history = await git_mgr.get_history(limit=10)
 
+# Transaction operations
+tx = await git_mgr.begin_transaction({"request": "update automation"})
+await git_mgr.stage_file_write(tx.transaction_id, "automations.yaml", "- id: motion_1\n")
+validation = await git_mgr.validate_transaction(tx.transaction_id)
+if validation.valid:
+    await git_mgr.commit_transaction(tx.transaction_id, "Apply automation updates")
+
 # YAML editing
 editor = YAMLEditor()
 result = editor.remove_yaml_entry(content, "- id: 'old_automation'")
+
+# Semantic YAML patch preview
+from aiocortex.models import YAMLPatchOperation
+preview = editor.preview_patch(
+    content,
+    [YAMLPatchOperation(op="set", path=["homeassistant", "name"], value="New Name")],
+)
 ```
 
 ## Architecture
@@ -138,6 +153,11 @@ pip install -e ".[dev]"
 pytest --cov=aiocortex
 ```
 
+## Contract Changes (0.3.0)
+
+- Public file/git manager methods now return strongly typed Pydantic models instead of raw dicts.
+- Consumers should migrate from dictionary key access to attribute access.
+
 ## License
 
 MIT

{aiocortex-0.2.0 → aiocortex-0.3.0}/README.md

@@ -14,8 +14,9 @@ pip install aiocortex
 
 - **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
+- **YAML editing** — Safe YAML read/write/parse utilities + semantic patch preview/apply helpers
 - **Pydantic models** — Typed data models for automations, scripts, helpers, files, git commits
+- **Transactions** — Durable plan/apply/abort flow with rollback metadata for multi-step config changes
 - **AI Instructions** — Bundled markdown instruction docs for AI-powered HA management (sync & async loaders)
 
 ## Quick Start
@@ -34,9 +35,23 @@ await git_mgr.init_repo()
 await git_mgr.commit_changes("Add automation: motion sensor light")
 history = await git_mgr.get_history(limit=10)
 
+# Transaction operations
+tx = await git_mgr.begin_transaction({"request": "update automation"})
+await git_mgr.stage_file_write(tx.transaction_id, "automations.yaml", "- id: motion_1\n")
+validation = await git_mgr.validate_transaction(tx.transaction_id)
+if validation.valid:
+    await git_mgr.commit_transaction(tx.transaction_id, "Apply automation updates")
+
 # YAML editing
 editor = YAMLEditor()
 result = editor.remove_yaml_entry(content, "- id: 'old_automation'")
+
+# Semantic YAML patch preview
+from aiocortex.models import YAMLPatchOperation
+preview = editor.preview_patch(
+    content,
+    [YAMLPatchOperation(op="set", path=["homeassistant", "name"], value="New Name")],
+)
 ```
 
 ## Architecture
@@ -105,6 +120,11 @@ pip install -e ".[dev]"
 pytest --cov=aiocortex
 ```
 
+## Contract Changes (0.3.0)
+
+- Public file/git manager methods now return strongly typed Pydantic models instead of raw dicts.
+- Consumers should migrate from dictionary key access to attribute access.
+
 ## License
 
 MIT

{aiocortex-0.2.0 → aiocortex-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aiocortex"
-version = "0.2.0"
+version = "0.3.0"
 description = "Async Python library for Home Assistant configuration management"
 readme = "README.md"
 license = "MIT"

{aiocortex-0.2.0 → aiocortex-0.3.0}/src/aiocortex/__init__.py

@@ -20,25 +20,46 @@ from .instructions import (
 )
 from .models import (
     AutomationConfig,
+    CheckpointResult,
+    CleanupResult,
     CommitInfo,
     CortexResponse,
+    FileAppendResult,
+    FileDeleteResult,
     FileInfo,
+    FilePathResult,
     FileWriteResult,
     HelperSpec,
     PendingChanges,
     PendingChangesSummary,
+    RestoreFilesResult,
+    RollbackResult,
     ScriptConfig,
     ServiceCallSpec,
+    TransactionAbortResult,
+    TransactionCommitResult,
+    TransactionOperation,
+    TransactionRollbackMetadata,
+    TransactionState,
+    TransactionValidationResult,
+    YAMLConflict,
+    YAMLPatchOperation,
+    YAMLPatchPreview,
 )
 
 __all__ = [
     "AsyncFileManager",
     "AutomationConfig",
+    "CheckpointResult",
+    "CleanupResult",
     "CommitInfo",
     "CortexError",
     "CortexResponse",
+    "FileAppendResult",
+    "FileDeleteResult",
     "FileError",
     "FileInfo",
+    "FilePathResult",
     "FileWriteResult",
     "GitError",
     "GitManager",
@@ -47,10 +68,21 @@ __all__ = [
     "PathSecurityError",
     "PendingChanges",
     "PendingChangesSummary",
+    "RestoreFilesResult",
+    "RollbackResult",
     "ScriptConfig",
     "ServiceCallSpec",
+    "TransactionAbortResult",
+    "TransactionCommitResult",
+    "TransactionOperation",
+    "TransactionRollbackMetadata",
+    "TransactionState",
+    "TransactionValidationResult",
+    "YAMLConflict",
     "YAMLEditor",
     "YAMLParseError",
+    "YAMLPatchOperation",
+    "YAMLPatchPreview",
     "__version__",
     "async_load_all_instructions",
     "async_load_instruction_file",

{aiocortex-0.2.0 → aiocortex-0.3.0}/src/aiocortex/_version.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{aiocortex-0.2.0 → aiocortex-0.3.0}/src/aiocortex/files/manager.py

@@ -16,6 +16,15 @@ import aiofiles
 import yaml
 
 from ..exceptions import FileError, PathSecurityError, YAMLParseError
+from ..models.files import (
+    FileAppendResult,
+    FileDeleteResult,
+    FileInfo,
+    FileWriteResult,
+    YAMLPatchOperation,
+    YAMLPatchPreview,
+)
+from .yaml_editor import YAMLEditor
 
 logger = logging.getLogger(__name__)
 
@@ -58,7 +67,7 @@ class AsyncFileManager:
         self,
         directory: str = "",
         pattern: str = "*",
-    ) -> list[dict[str, object]]:
+    ) -> list[FileInfo]:
         """List files in *directory* matching *pattern* (recursive glob)."""
         try:
             dir_path = self._get_full_path(directory)
@@ -66,22 +75,22 @@ class AsyncFileManager:
             if not dir_path.exists():
                 return []
 
-            files: list[dict[str, object]] = []
+            files: list[FileInfo] = []
             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"),
-                        }
+                        FileInfo(
+                            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"]))
+            return sorted(files, key=lambda file_info: file_info.path)
         except PathSecurityError:
             raise
         except Exception as exc:
@@ -107,7 +116,7 @@ class AsyncFileManager:
             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]:
+    async def write_file(self, file_path: str, content: str) -> FileWriteResult:
         """Write *content* to *file_path*, creating parent directories as needed.
 
         Returns a result dict with *success*, *path*, and *size*.
@@ -126,14 +135,14 @@ class AsyncFileManager:
 
             logger.info("Wrote file: %s (%d bytes)", file_path, len(content))
 
-            return {"success": True, "path": file_path, "size": len(content)}
+            return FileWriteResult(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]:
+    async def append_file(self, file_path: str, content: str) -> FileAppendResult:
         """Append *content* to *file_path*, creating it if it doesn't exist."""
         try:
             full_path = self._get_full_path(file_path)
@@ -152,19 +161,19 @@ class AsyncFileManager:
 
             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),
-            }
+            return FileAppendResult(
+                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]:
+    async def delete_file(self, file_path: str) -> FileDeleteResult:
         """Delete *file_path*.
 
         Returns a result dict with *success* and *path*.
@@ -178,7 +187,7 @@ class AsyncFileManager:
             full_path.unlink()
             logger.info("Deleted file: %s", file_path)
 
-            return {"success": True, "path": file_path}
+            return FileDeleteResult(success=True, path=file_path)
         except (FileNotFoundError, PathSecurityError):
             raise
         except Exception as exc:
@@ -194,3 +203,24 @@ class AsyncFileManager:
         except yaml.YAMLError as exc:
             logger.error("YAML parse error in %s: %s", file_path, exc)
             raise YAMLParseError(f"Invalid YAML: {exc}") from exc
+
+    async def preview_yaml_patch(
+        self,
+        file_path: str,
+        operations: list[YAMLPatchOperation],
+    ) -> YAMLPatchPreview:
+        """Preview semantic YAML patch operations without writing file changes."""
+        content = await self.read_file(file_path)
+        return YAMLEditor.preview_patch(content, operations)
+
+    async def apply_yaml_patch(
+        self,
+        file_path: str,
+        operations: list[YAMLPatchOperation],
+    ) -> YAMLPatchPreview:
+        """Apply semantic YAML patch operations and persist updated YAML content."""
+        content = await self.read_file(file_path)
+        preview = YAMLEditor.apply_patch(content, operations)
+        if preview.success:
+            await self.write_file(file_path, preview.patched_content)
+        return preview

aiocortex-0.3.0/src/aiocortex/files/yaml_editor.py

@@ -0,0 +1,235 @@
+"""YAML editor utility for safe YAML file modifications.
+
+Ported from ``app/utils/yaml_editor.py`` in the HA Vibecode Agent add-on.
+"""
+
+from __future__ import annotations
+
+import copy
+import difflib
+import re
+from typing import Any
+
+import yaml
+
+from ..models.files import YAMLConflict, YAMLPatchOperation, YAMLPatchPreview
+
+
+class YAMLEditor:
+    """Utility for editing YAML files while preserving structure."""
+
+    @staticmethod
+    def remove_lines_from_end(content: str, num_lines: int) -> str:
+        """Remove *num_lines* from the end of *content*."""
+        lines = content.rstrip().split("\n")
+        if num_lines >= len(lines):
+            return ""
+        return "\n".join(lines[:-num_lines]) + "\n"
+
+    @staticmethod
+    def remove_empty_yaml_section(content: str, section_name: str) -> str:
+        """Remove an empty YAML section (e.g. ``lovelace:`` with only empty sub-keys)."""
+        # Pattern: comment + section with only empty subsections
+        pattern = rf"\n# .*{section_name.title()}.*\n{section_name}:\s*\n\s+\w+:\s*\n(?=\S|\Z)"
+        content = re.sub(pattern, "\n", content, flags=re.IGNORECASE)
+
+        # Also try without a preceding comment
+        pattern = rf"\n{section_name}:\s*\n\s+\w+:\s*\n(?=\S|\Z)"
+        content = re.sub(pattern, "\n", content, flags=re.IGNORECASE)
+
+        return content
+
+    @staticmethod
+    def remove_yaml_entry(
+        content: str,
+        section: str,
+        key: str,
+    ) -> tuple[str, bool]:
+        """Remove a specific entry from a YAML section.
+
+        Returns ``(modified_content, was_found)``.
+        """
+        pattern = rf"    {re.escape(key)}:\s*\n(?:      .*\n)*"
+
+        if re.search(pattern, content):
+            modified = re.sub(pattern, "", content)
+            modified = YAMLEditor.remove_empty_yaml_section(modified, section)
+            return modified, True
+
+        return content, False
+
+    @staticmethod
+    def _get_path(data: Any, path: list[str | int]) -> tuple[bool, Any]:
+        current = data
+        for segment in path:
+            if isinstance(segment, int):
+                if not isinstance(current, list) or segment >= len(current):
+                    return False, None
+                current = current[segment]
+                continue
+
+            if not isinstance(current, dict) or segment not in current:
+                return False, None
+            current = current[segment]
+
+        return True, current
+
+    @staticmethod
+    def _ensure_parent(data: Any, path: list[str | int]) -> tuple[bool, Any]:
+        current = data
+        for segment in path[:-1]:
+            if isinstance(segment, int):
+                if not isinstance(current, list):
+                    return False, None
+                if segment >= len(current):
+                    return False, None
+                current = current[segment]
+            else:
+                if not isinstance(current, dict):
+                    return False, None
+                if segment not in current or not isinstance(current[segment], (dict, list)):
+                    current[segment] = {}
+                current = current[segment]
+
+        return True, current
+
+    @staticmethod
+    def _set_path(data: Any, path: list[str | int], value: Any) -> bool:
+        if not path:
+            return False
+
+        ok, parent = YAMLEditor._ensure_parent(data, path)
+        if not ok:
+            return False
+
+        leaf = path[-1]
+        if isinstance(leaf, int):
+            if not isinstance(parent, list):
+                return False
+            if leaf == len(parent):
+                parent.append(value)
+                return True
+            if 0 <= leaf < len(parent):
+                parent[leaf] = value
+                return True
+            return False
+
+        if not isinstance(parent, dict):
+            return False
+        parent[leaf] = value
+        return True
+
+    @staticmethod
+    def _remove_path(data: Any, path: list[str | int]) -> bool:
+        if not path:
+            return False
+
+        ok, parent = YAMLEditor._ensure_parent(data, path)
+        if not ok:
+            return False
+
+        leaf = path[-1]
+        if isinstance(leaf, int):
+            if not isinstance(parent, list) or not (0 <= leaf < len(parent)):
+                return False
+            del parent[leaf]
+            return True
+
+        if not isinstance(parent, dict) or leaf not in parent:
+            return False
+        del parent[leaf]
+        return True
+
+    @staticmethod
+    def _merge_list_item(data: Any, path: list[str | int], value: Any, merge_key: str) -> bool:
+        ok, current = YAMLEditor._get_path(data, path)
+        if not ok or not isinstance(current, list) or not isinstance(value, dict):
+            return False
+
+        key_value = value.get(merge_key)
+        if key_value is None:
+            return False
+
+        for index, item in enumerate(current):
+            if isinstance(item, dict) and item.get(merge_key) == key_value:
+                current[index] = {**item, **value}
+                return True
+
+        current.append(value)
+        return True
+
+    @staticmethod
+    def normalized_diff(before: str, after: str) -> str:
+        """Return deterministic unified diff output for content comparisons."""
+        before_lines = before.rstrip().splitlines()
+        after_lines = after.rstrip().splitlines()
+        return "\n".join(
+            difflib.unified_diff(
+                before_lines,
+                after_lines,
+                fromfile="before.yaml",
+                tofile="after.yaml",
+                lineterm="",
+            )
+        )
+
+    @staticmethod
+    def preview_patch(
+        content: str,
+        operations: list[YAMLPatchOperation],
+    ) -> YAMLPatchPreview:
+        """Preview semantic YAML mutations and report conflicts before apply."""
+        try:
+            parsed = yaml.safe_load(content) if content.strip() else {}
+        except yaml.YAMLError as exc:
+            return YAMLPatchPreview(
+                success=False,
+                operations_applied=0,
+                conflicts=[YAMLConflict(path="<root>", reason=f"Invalid YAML: {exc}")],
+                patched_content=content,
+                diff="",
+            )
+
+        data = parsed or {}
+        mutated = copy.deepcopy(data)
+        conflicts: list[YAMLConflict] = []
+        applied = 0
+
+        for operation in operations:
+            if operation.op == "set":
+                ok = YAMLEditor._set_path(mutated, operation.path, operation.value)
+            elif operation.op == "remove":
+                ok = YAMLEditor._remove_path(mutated, operation.path)
+            elif not operation.merge_key:
+                ok = False
+            else:
+                ok = YAMLEditor._merge_list_item(
+                    mutated,
+                    operation.path,
+                    operation.value,
+                    operation.merge_key,
+                )
+
+            if ok:
+                applied += 1
+            else:
+                conflicts.append(
+                    YAMLConflict(
+                        path="/".join(str(part) for part in operation.path),
+                        reason=f"Could not apply operation '{operation.op}'",
+                    )
+                )
+
+        patched_content = yaml.safe_dump(mutated, sort_keys=True, allow_unicode=True)
+        return YAMLPatchPreview(
+            success=not conflicts,
+            operations_applied=applied,
+            conflicts=conflicts,
+            patched_content=patched_content,
+            diff=YAMLEditor.normalized_diff(content, patched_content),
+        )
+
+    @staticmethod
+    def apply_patch(content: str, operations: list[YAMLPatchOperation]) -> YAMLPatchPreview:
+        """Apply semantic YAML mutations, returning final content and diff metadata."""
+        return YAMLEditor.preview_patch(content, operations)