aiocortex 0.1.0__py3-none-any.whl

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/_version.py

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

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/files/__init__.py

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

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

aiocortex/files/yaml_editor.py

@@ -0,0 +1,52 @@
+"""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 re
+
+
+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

aiocortex/git/__init__.py

@@ -0,0 +1,12 @@
+"""Git versioning with dulwich (no git binary required)."""
+
+from .filters import should_include_path
+from .manager import GitManager
+from .sync import sync_config_to_shadow, sync_shadow_to_config
+
+__all__ = [
+    "GitManager",
+    "should_include_path",
+    "sync_config_to_shadow",
+    "sync_shadow_to_config",
+]

aiocortex/git/cleanup.py

@@ -0,0 +1,200 @@
+"""History truncation for the shadow git repository.
+
+Uses dulwich for commit-chain rewriting where possible.  Falls back to
+``git clone --depth`` via subprocess if the ``git`` binary is available.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from dulwich.repo import Repo
+
+from ..exceptions import GitError
+
+logger = logging.getLogger(__name__)
+
+
+def _git_binary_available() -> bool:
+    """Return ``True`` if the ``git`` CLI is on ``$PATH``."""
+    try:
+        result = subprocess.run(
+            ["git", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def truncate_history(
+    repo_path: Path,
+    commits_to_keep: int,
+) -> int:
+    """Truncate the repository at *repo_path* to at most *commits_to_keep* commits.
+
+    Returns the number of commits after truncation.
+
+    The strategy is:
+
+    1. If the ``git`` binary is available, use ``git clone --depth`` into a
+       temp dir, then swap ``.git`` directories.  This is the most reliable
+       approach on HA OS (where git is available in the container).
+    2. Otherwise raise :class:`GitError` — pure-dulwich history rewriting is
+       a future enhancement.
+    """
+    repo_path = repo_path.resolve()
+    git_dir = repo_path / ".git"
+
+    if not git_dir.is_dir():
+        raise GitError(f"No .git directory at {repo_path}")
+
+    # --- Strategy 1: git clone --depth ---
+    if _git_binary_available():
+        return _truncate_via_clone(repo_path, commits_to_keep)
+
+    # --- Strategy 2: dulwich-native (basic orphan graft) ---
+    return _truncate_via_dulwich(repo_path, commits_to_keep)
+
+
+def _truncate_via_clone(repo_path: Path, commits_to_keep: int) -> int:
+    """Clone with ``--depth`` and swap ``.git`` directories."""
+    git_dir = repo_path / ".git"
+
+    # Detect current branch
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        branch = result.stdout.strip() or "master"
+    except Exception:
+        branch = "master"
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        clone_path = os.path.join(tmpdir, "cloned_repo")
+        repo_url = f"file://{repo_path}"
+
+        logger.info("Cloning repository with depth=%d from %s ...", commits_to_keep, repo_url)
+        result = subprocess.run(
+            [
+                "git",
+                "clone",
+                "--depth",
+                str(commits_to_keep),
+                "--branch",
+                branch,
+                "--single-branch",
+                repo_url,
+                clone_path,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=600,
+        )
+        if result.returncode != 0:
+            raise GitError(f"git clone failed: {result.stderr}")
+
+        cloned_git_dir = os.path.join(clone_path, ".git")
+        if not os.path.isdir(cloned_git_dir):
+            raise GitError("Cloned .git directory does not exist")
+
+        # Swap .git
+        backup_git = os.path.join(tmpdir, "git_backup")
+        shutil.copytree(str(git_dir), backup_git)
+        shutil.rmtree(str(git_dir))
+        shutil.copytree(cloned_git_dir, str(git_dir))
+
+        logger.info("Replaced .git directory with shallow clone")
+
+    # Optional gc
+    try:
+        subprocess.run(
+            ["git", "gc", "--prune=now", "--quiet"],
+            cwd=str(repo_path),
+            capture_output=True,
+            timeout=600,
+        )
+    except Exception as exc:
+        logger.warning("git gc after truncation failed: %s", exc)
+
+    # Return final count
+    try:
+        result = subprocess.run(
+            ["git", "rev-list", "--count", "--first-parent", "HEAD"],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return int(result.stdout.strip())
+    except Exception:
+        return commits_to_keep
+
+
+def _truncate_via_dulwich(repo_path: Path, commits_to_keep: int) -> int:
+    """Basic dulwich-native truncation using orphan commit grafting.
+
+    Walks the commit chain, keeps *commits_to_keep* most recent commits,
+    and rewrites the oldest-kept commit to have no parents (orphan root).
+    Then packs and prunes unreachable objects.
+    """
+    repo = Repo(str(repo_path))
+
+    try:
+        head_sha = repo.head()
+    except KeyError:
+        raise GitError("Repository has no HEAD") from None
+
+    # Walk the first-parent chain
+    chain: list[bytes] = []
+    current = head_sha
+    while current and len(chain) < commits_to_keep + 1:
+        chain.append(current)
+        commit = repo.get_object(current)
+        current = commit.parents[0] if commit.parents else None
+
+    if len(chain) <= commits_to_keep:
+        # Nothing to truncate
+        return len(chain)
+
+    # Rewrite the oldest kept commit to have no parents
+    oldest_kept_sha = chain[commits_to_keep - 1]
+    oldest_kept = repo.get_object(oldest_kept_sha).copy()
+    oldest_kept.parents = []
+
+    # Store the rewritten commit
+    repo.object_store.add_object(oldest_kept)
+
+    # Rewrite the chain from oldest-kept to HEAD
+    sha_map: dict[bytes, bytes] = {oldest_kept_sha: oldest_kept.id}
+
+    for i in range(commits_to_keep - 2, -1, -1):
+        old_sha = chain[i]
+        commit = repo.get_object(old_sha).copy()
+        # Replace parent references
+        new_parents = []
+        for p in commit.parents:
+            new_parents.append(sha_map.get(p, p))
+        commit.parents = new_parents
+        repo.object_store.add_object(commit)
+        sha_map[old_sha] = commit.id
+
+    # Update HEAD/refs to point to new chain
+    new_head = sha_map.get(head_sha, head_sha)
+    for ref in repo.get_refs():
+        if repo.get_refs()[ref] == head_sha:
+            repo.refs[ref] = new_head
+
+    repo.close()
+
+    return commits_to_keep

aiocortex/git/filters.py

@@ -0,0 +1,111 @@
+"""Path filtering — decide which files should be tracked in the shadow repo.
+
+Ported from ``GitManager._should_include_path()`` in the HA Vibecode Agent
+add-on.  This module is pure logic with no git or filesystem side-effects.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+
+# Directories excluded at the top level of /config
+_EXCLUDED_DIRS: frozenset[str] = frozenset(
+    {
+        ".storage",
+        ".cloud",
+        ".homeassistant",
+        "www",
+        "media",
+        "storage",
+        "tmp",
+        "node_modules",
+        "__pycache__",
+    }
+)
+
+# Filename-level exclusion patterns
+_SECRET_FILES: frozenset[str] = frozenset({"secrets.yaml", ".secrets.yaml"})
+_SECRET_EXTS: tuple[str, ...] = ("*.pem", "*.key", "*.crt")
+_DB_PATTERNS: tuple[str, ...] = (
+    "*.db",
+    "*.db-shm",
+    "*.db-wal",
+    "*.db-journal",
+    "*.sqlite",
+    "*.sqlite3",
+    "home-assistant_v2.db*",
+)
+_LOG_PATTERNS: tuple[str, ...] = ("*.log", "*.log.*", "home-assistant.log")
+_BACKUP_PATTERNS: tuple[str, ...] = ("*.bak", "*.backup", "*.old", "*.tmp", "*.temp", "*~")
+_DIR_PREFIXES: tuple[str, ...] = (
+    ".storage/",
+    ".cloud/",
+    ".homeassistant/",
+    "www/",
+    "media/",
+    "storage/",
+    "tmp/",
+)
+
+
+def should_include_path(
+    rel_path: str,
+    is_dir: bool,
+    *,
+    shadow_dir_name: str = "cortex_git",
+) -> bool:
+    """Return ``True`` if *rel_path* (relative to ``/config``) should be tracked.
+
+    Parameters
+    ----------
+    rel_path:
+        Forward-slash normalised path relative to the HA config directory.
+    is_dir:
+        Whether the path represents a directory.
+    shadow_dir_name:
+        Name of the shadow-repo directory to exclude (default ``cortex_git``).
+    """
+    rel_path = rel_path.replace(os.sep, "/")
+    parts = rel_path.split("/")
+
+    # Skip shadow repo and any .git directories
+    if parts[0] in (".git", shadow_dir_name):
+        return False
+
+    # Directory-level filtering
+    if is_dir:
+        return parts[0] not in _EXCLUDED_DIRS
+
+    filename = parts[-1]
+
+    # Secrets / keys
+    if filename in _SECRET_FILES:
+        return False
+    if any(fnmatch.fnmatch(filename, pat) for pat in _SECRET_EXTS):
+        return False
+
+    # DB files
+    if any(
+        fnmatch.fnmatch(filename, pat) or fnmatch.fnmatch(rel_path, pat) for pat in _DB_PATTERNS
+    ):
+        return False
+
+    # Logs
+    if any(
+        fnmatch.fnmatch(filename, pat) or fnmatch.fnmatch(rel_path, pat) for pat in _LOG_PATTERNS
+    ):
+        return False
+
+    # Backup-like files
+    if any(
+        fnmatch.fnmatch(filename, pat) or fnmatch.fnmatch(rel_path, pat)
+        for pat in _BACKUP_PATTERNS
+    ):
+        return False
+
+    # Files inside heavy/internal dirs (if they weren't pruned at dir level)
+    if any(rel_path.startswith(prefix) for prefix in _DIR_PREFIXES):
+        return False
+
+    return True