git-aware-coding-agent 1.0.0__py3-none-any.whl

avos_cli/commands/ingest_pr.py

@@ -0,0 +1,239 @@
+"""Single-PR ingest command orchestrator.
+
+Implements `avos ingest-pr org/repo PR_NUMBER` to ingest a specific PR
+after it has been pushed/merged. Reuses the existing PR artifact builder
+and hash store for deduplication.
+
+Exit codes:
+    0: success (stored or skipped)
+    1: precondition failure (config missing, invalid args)
+    2: hard external failure (GitHub API, Memory API)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from avos_cli.artifacts.pr_builder import PRThreadBuilder
+from avos_cli.config.hash_store import IngestHashStore
+from avos_cli.config.manager import load_config
+from avos_cli.exceptions import AvosError, ConfigurationNotInitializedError
+from avos_cli.models.artifacts import PRArtifact
+from avos_cli.services.github_client import GitHubClient
+from avos_cli.services.memory_client import AvosMemoryClient
+from avos_cli.utils.logger import get_logger
+from avos_cli.utils.output import (
+    print_error,
+    print_info,
+    print_json,
+    render_kv_panel,
+)
+
+_log = get_logger("commands.ingest_pr")
+
+
+class IngestPROrchestrator:
+    """Orchestrates the `avos ingest-pr` command.
+
+    Fetches a single PR by number, builds its artifact, checks for
+    duplicates via content hash, and stores in Avos Memory.
+
+    Args:
+        memory_client: Avos Memory API client.
+        github_client: GitHub REST API client.
+        hash_store: Content hash store for deduplication.
+        repo_root: Path to the repository root.
+    """
+
+    def __init__(
+        self,
+        memory_client: AvosMemoryClient,
+        github_client: GitHubClient,
+        hash_store: IngestHashStore,
+        repo_root: Path,
+    ) -> None:
+        self._memory = memory_client
+        self._github = github_client
+        self._hash_store = hash_store
+        self._repo_root = repo_root
+        self._pr_builder = PRThreadBuilder()
+
+    def run(
+        self, repo_slug: str, pr_number: int, json_output: bool = False
+    ) -> int:
+        """Execute the single-PR ingest flow.
+
+        Args:
+            repo_slug: Repository identifier in 'org/repo' format.
+            pr_number: PR number to ingest.
+            json_output: If True, emit JSON output instead of human UI.
+
+        Returns:
+            Exit code: 0 success, 1 precondition, 2 hard error.
+        """
+        if not self._validate_slug(repo_slug):
+            if json_output:
+                print_json(
+                    success=False,
+                    data=None,
+                    error={
+                        "code": "REPOSITORY_CONTEXT_ERROR",
+                        "message": "Invalid repo slug. Expected 'org/repo'.",
+                        "hint": None,
+                        "retryable": False,
+                    },
+                )
+            else:
+                print_error("[REPOSITORY_CONTEXT_ERROR] Invalid repo slug. Expected 'org/repo'.")
+            return 1
+
+        owner, repo = repo_slug.split("/", 1)
+
+        try:
+            config = load_config(self._repo_root)
+        except ConfigurationNotInitializedError as e:
+            if json_output:
+                print_json(
+                    success=False,
+                    data=None,
+                    error={
+                        "code": "CONFIG_NOT_INITIALIZED",
+                        "message": str(e),
+                        "hint": "Run 'avos connect org/repo' first.",
+                        "retryable": False,
+                    },
+                )
+            else:
+                print_error(f"[CONFIG_NOT_INITIALIZED] {e}")
+            return 1
+        except AvosError as e:
+            if json_output:
+                print_json(
+                    success=False,
+                    data=None,
+                    error={
+                        "code": e.code,
+                        "message": str(e),
+                        "hint": getattr(e, "hint", None),
+                        "retryable": getattr(e, "retryable", False),
+                    },
+                )
+            else:
+                print_error(f"[{e.code}] {e}")
+            return 1
+
+        memory_id = config.memory_id
+
+        try:
+            pr_detail = self._github.get_pr_details(owner, repo, pr_number)
+        except AvosError as e:
+            if json_output:
+                print_json(
+                    success=False,
+                    data=None,
+                    error={
+                        "code": e.code,
+                        "message": f"Failed to fetch PR #{pr_number}: {e}",
+                        "hint": getattr(e, "hint", None),
+                        "retryable": getattr(e, "retryable", True),
+                    },
+                )
+            else:
+                print_error(f"[{e.code}] Failed to fetch PR #{pr_number}: {e}")
+            return 2
+
+        artifact = self._build_pr_artifact(repo, owner, pr_detail)
+        text = self._pr_builder.build(artifact)
+        content_hash = self._pr_builder.content_hash(artifact)
+
+        if self._hash_store.contains(content_hash):
+            result = {
+                "pr_number": pr_number,
+                "action": "skipped",
+                "note_id": None,
+                "reason": "already_ingested",
+            }
+            if json_output:
+                print_json(success=True, data=result, error=None)
+            else:
+                print_info(f"PR #{pr_number} already ingested. Skipping.")
+            return 0
+
+        try:
+            note_response = self._memory.add_memory(memory_id=memory_id, content=text)
+            note_id = note_response.note_id
+        except AvosError as e:
+            if json_output:
+                print_json(
+                    success=False,
+                    data=None,
+                    error={
+                        "code": e.code,
+                        "message": f"Failed to store PR #{pr_number}: {e}",
+                        "hint": getattr(e, "hint", None),
+                        "retryable": getattr(e, "retryable", True),
+                    },
+                )
+            else:
+                print_error(f"[{e.code}] Failed to store PR #{pr_number}: {e}")
+            return 2
+
+        self._hash_store.add(content_hash, "pr", str(pr_number))
+        self._hash_store.save()
+
+        result = {
+            "pr_number": pr_number,
+            "action": "stored",
+            "note_id": note_id,
+            "reason": None,
+        }
+
+        if json_output:
+            print_json(success=True, data=result, error=None)
+        else:
+            render_kv_panel(
+                f"PR #{pr_number} Ingested",
+                [
+                    ("Title", artifact.title[:60] + "..." if len(artifact.title) > 60 else artifact.title),
+                    ("Author", artifact.author),
+                    ("Files", str(len(artifact.files))),
+                    ("Note ID", note_id[:12] + "..." if len(note_id) > 12 else note_id),
+                ],
+                style="success",
+            )
+
+        return 0
+
+    def _build_pr_artifact(
+        self, repo: str, owner: str, pr_detail: dict[str, Any]
+    ) -> PRArtifact:
+        """Transform GitHub PR detail dict into a PRArtifact."""
+        files = [f["filename"] for f in pr_detail.get("files", [])]
+        comments = pr_detail.get("comments", [])
+        reviews = pr_detail.get("reviews", [])
+        discussion_parts: list[str] = []
+        for c in comments:
+            user = c.get("user", {}).get("login", "unknown")
+            discussion_parts.append(f"{user}: {c.get('body', '')}")
+        for r in reviews:
+            user = r.get("user", {}).get("login", "unknown")
+            discussion_parts.append(f"{user} ({r.get('state', '')}): {r.get('body', '')}")
+
+        return PRArtifact(
+            repo=f"{owner}/{repo}",
+            pr_number=pr_detail["number"],
+            title=pr_detail.get("title", ""),
+            author=pr_detail.get("user", {}).get("login", "unknown"),
+            merged_date=pr_detail.get("merged_at"),
+            files=files,
+            description=pr_detail.get("body"),
+            discussion="\n".join(discussion_parts) if discussion_parts else None,
+        )
+
+    @staticmethod
+    def _validate_slug(slug: str) -> bool:
+        if not slug or "/" not in slug:
+            return False
+        parts = slug.split("/", 1)
+        return bool(parts[0]) and bool(parts[1])

avos_cli/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration management for AVOS CLI."""

avos_cli/config/hash_store.py

@@ -0,0 +1,93 @@
+"""Ingest hash store for artifact deduplication.
+
+Manages .avos/ingest_hashes.json which maps content hashes to metadata.
+Used by the ingest command to skip already-stored artifacts on re-runs.
+Each entry stores artifact_type, source_id, and stored_at timestamp.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from avos_cli.config.state import atomic_write
+from avos_cli.utils.logger import get_logger
+
+_log = get_logger("config.hash_store")
+
+_HASH_STORE_FILENAME = "ingest_hashes.json"
+
+
+class IngestHashStore:
+    """Manages the content hash store for ingest deduplication.
+
+    Args:
+        avos_dir: Path to the .avos directory.
+    """
+
+    def __init__(self, avos_dir: Path) -> None:
+        self._path = avos_dir / _HASH_STORE_FILENAME
+        self._store: dict[str, dict[str, str]] = {}
+
+    def load(self) -> None:
+        """Load the hash store from disk. Quarantines corrupt files."""
+        if not self._path.exists():
+            self._store = {}
+            return
+
+        try:
+            content = self._path.read_text(encoding="utf-8")
+            if not content.strip():
+                self._store = {}
+                return
+            data = json.loads(content)
+            if not isinstance(data, dict):
+                _log.warning("Hash store is not a dict, treating as corrupt")
+                self._quarantine()
+                self._store = {}
+                return
+            self._store = data
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            _log.warning("Corrupt hash store, quarantining: %s", self._path)
+            self._quarantine()
+            self._store = {}
+
+    def save(self) -> None:
+        """Persist the hash store to disk atomically."""
+        content = json.dumps(self._store, indent=2, sort_keys=True)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write(self._path, content)
+
+    def contains(self, content_hash: str) -> bool:
+        """Check if a content hash is already stored."""
+        return content_hash in self._store
+
+    def add(self, content_hash: str, artifact_type: str, source_id: str) -> None:
+        """Add a content hash with metadata. Idempotent for duplicates."""
+        if content_hash in self._store:
+            return
+        self._store[content_hash] = {
+            "artifact_type": artifact_type,
+            "source_id": source_id,
+            "stored_at": datetime.now(tz=timezone.utc).isoformat(),
+        }
+
+    def get_entry(self, content_hash: str) -> dict[str, str] | None:
+        """Get the metadata entry for a hash, or None if not found."""
+        return self._store.get(content_hash)
+
+    def count(self) -> int:
+        """Return the number of stored hashes."""
+        return len(self._store)
+
+    def _quarantine(self) -> None:
+        """Move a corrupt hash store file to a .corrupt backup."""
+        ts = int(time.time())
+        corrupt_path = self._path.with_suffix(f"{self._path.suffix}.corrupt.{ts}")
+        try:
+            self._path.rename(corrupt_path)
+            _log.warning("Quarantined: %s -> %s", self._path, corrupt_path)
+        except OSError as e:
+            _log.error("Failed to quarantine %s: %s", self._path, e)

avos_cli/config/lock.py

@@ -0,0 +1,122 @@
+"""Ingest lock manager for preventing concurrent ingest runs.
+
+Uses a JSON lock file (.avos/ingest.lock) containing PID and timestamp.
+Supports stale-lock detection via PID liveness check and configurable
+time threshold (default 1 hour).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from avos_cli.exceptions import IngestLockError
+from avos_cli.utils.logger import get_logger
+
+_log = get_logger("config.lock")
+
+_LOCK_FILENAME = "ingest.lock"
+_DEFAULT_STALE_THRESHOLD = 3600  # 1 hour
+
+
+class IngestLockManager:
+    """Manages the ingest lock file for single-process exclusion.
+
+    Args:
+        avos_dir: Path to the .avos directory.
+        stale_threshold_seconds: Seconds after which a lock with a dead PID
+            is considered stale and can be broken.
+    """
+
+    def __init__(
+        self,
+        avos_dir: Path,
+        stale_threshold_seconds: int = _DEFAULT_STALE_THRESHOLD,
+    ) -> None:
+        self._lock_path = avos_dir / _LOCK_FILENAME
+        self._stale_threshold = stale_threshold_seconds
+
+    def acquire(self) -> None:
+        """Acquire the ingest lock.
+
+        Raises:
+            IngestLockError: If another live process holds the lock.
+        """
+        if self._lock_path.exists():
+            existing = self._read_lock()
+            if existing is None:
+                _log.warning("Removing corrupt lock file: %s", self._lock_path)
+                self._lock_path.unlink(missing_ok=True)
+            elif self._is_stale(existing):
+                _log.warning(
+                    "Breaking stale lock (pid=%d, age=%.0fs)",
+                    int(existing["pid"]),
+                    time.time() - float(existing["acquired_at"]),
+                )
+                self._lock_path.unlink(missing_ok=True)
+            else:
+                pid = int(existing["pid"])
+                raise IngestLockError(
+                    f"Ingest lock held by pid {pid}",
+                    holder_pid=pid,
+                )
+
+        self._write_lock()
+
+    def release(self) -> None:
+        """Release the ingest lock. Safe to call even if not held."""
+        self._lock_path.unlink(missing_ok=True)
+
+    def is_locked(self) -> bool:
+        """Check whether the lock file exists."""
+        return self._lock_path.exists()
+
+    def __enter__(self) -> IngestLockManager:
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> None:
+        self.release()
+
+    def _write_lock(self) -> None:
+        """Write the lock file with current PID and timestamp."""
+        data = {"pid": os.getpid(), "acquired_at": time.time()}
+        self._lock_path.write_text(json.dumps(data), encoding="utf-8")
+
+    def _read_lock(self) -> dict[str, int | float] | None:
+        """Read and parse the lock file. Returns None if corrupt."""
+        try:
+            content = self._lock_path.read_text(encoding="utf-8")
+            if not content.strip():
+                return None
+            raw = json.loads(content)
+            if not isinstance(raw, dict):
+                return None
+            if "pid" not in raw or "acquired_at" not in raw:
+                return None
+            return {"pid": int(raw["pid"]), "acquired_at": float(raw["acquired_at"])}
+        except (json.JSONDecodeError, OSError, ValueError, TypeError):
+            return None
+
+    def _is_stale(self, lock_data: dict[str, int | float]) -> bool:
+        """Determine if a lock is stale (old AND holder PID is dead).
+
+        A lock is stale only when BOTH conditions are met:
+        1. The lock age exceeds the stale threshold.
+        2. The holder PID is no longer alive.
+        """
+        age = time.time() - float(lock_data["acquired_at"])
+        if age < self._stale_threshold:
+            return False
+        return not self._pid_alive(int(lock_data["pid"]))
+
+    @staticmethod
+    def _pid_alive(pid: int) -> bool:
+        """Check if a process with the given PID is alive."""
+        try:
+            os.kill(pid, 0)
+            return True
+        except (OSError, ProcessLookupError):
+            return False

avos_cli/config/manager.py

@@ -0,0 +1,180 @@
+"""Configuration manager for AVOS CLI.
+
+Handles repo root detection, config load/save with environment variable
+overlay, and .avos directory management. Config resolution priority:
+env vars > config file > defaults.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from avos_cli.config.state import atomic_write, read_json_safe
+from avos_cli.exceptions import (
+    ConfigurationNotInitializedError,
+    ConfigurationValidationError,
+    RepositoryContextError,
+)
+from avos_cli.models.config import RepoConfig
+
+_CONFIG_FILENAME = "config.json"
+_AVOS_DIR = ".avos"
+
+
+def find_repo_root(start: Path) -> Path:
+    """Walk up from start directory to find the Git repository root.
+
+    Detects both standard repos (.git directory) and worktrees (.git file).
+
+    Args:
+        start: Directory to start searching from.
+
+    Returns:
+        Path to the repository root.
+
+    Raises:
+        RepositoryContextError: If no .git is found.
+    """
+    current = start.resolve()
+    while True:
+        git_path = current / ".git"
+        if git_path.exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    raise RepositoryContextError(f"No Git repository found at or above: {start}")
+
+
+def load_config(repo_root: Path) -> RepoConfig:
+    """Load repository configuration from .avos/config.json with env overlay.
+
+    Resolution priority: env vars > config file values > defaults.
+
+    Args:
+        repo_root: Path to the repository root (must contain .avos/).
+
+    Returns:
+        Validated RepoConfig instance.
+
+    Raises:
+        ConfigurationNotInitializedError: If .avos/config.json doesn't exist.
+        ConfigurationValidationError: If config is malformed or invalid.
+    """
+    config_path = repo_root / _AVOS_DIR / _CONFIG_FILENAME
+
+    if not config_path.exists():
+        raise ConfigurationNotInitializedError()
+
+    raw_data = read_json_safe(config_path)
+    if raw_data is None:
+        raise ConfigurationValidationError(
+            f"Config file is corrupt or unreadable: {config_path}"
+        )
+
+    data: dict[str, Any] = dict(raw_data)
+    _apply_env_overlay(data)
+
+    try:
+        return RepoConfig(**data)
+    except ValidationError as e:
+        raise ConfigurationValidationError(
+            f"Invalid configuration in {config_path}: {e}"
+        ) from e
+
+
+def connected_repo_slug(repo_root: Path) -> str | None:
+    """Return the repository slug persisted by ``avos connect`` (authoritative context).
+
+    After a successful connect, ``repo`` in ``.avos/config.json`` is the
+    canonical ``org/repo`` for this working copy. Pass it as ``default_repo``
+    to :class:`~avos_cli.parsers.reference_parser.ReferenceParser` when the
+    user omits owner/repo (e.g. ``PR #1245``, ``Commit 8c3a1b2``).
+
+    Args:
+        repo_root: Git repository root containing ``.avos/config.json``.
+
+    Returns:
+        Connected slug, or ``None`` if the project was never connected.
+
+    Raises:
+        ConfigurationValidationError: If the config file exists but is invalid.
+    """
+    try:
+        return load_config(repo_root).repo
+    except ConfigurationNotInitializedError:
+        return None
+
+
+def _apply_env_overlay(data: dict[str, Any]) -> None:
+    """Apply environment variable overrides to config data dict.
+
+    Env vars take precedence over file values. Supports:
+    AVOS_API_KEY, AVOS_API_URL, GITHUB_TOKEN, AVOS_DEVELOPER,
+    AVOS_LLM_PROVIDER, AVOS_LLM_MODEL.
+    """
+    env_map = {
+        "AVOS_API_KEY": "api_key",
+        "AVOS_API_URL": "api_url",
+        "GITHUB_TOKEN": "github_token",
+        "AVOS_DEVELOPER": "developer",
+    }
+    for env_var, config_key in env_map.items():
+        value = os.environ.get(env_var)
+        if value is not None:
+            data[config_key] = value
+
+    llm_data = data.get("llm", {})
+    if not isinstance(llm_data, dict):
+        llm_data = {}
+    llm_provider_env = os.environ.get("AVOS_LLM_PROVIDER")
+    llm_model_env = os.environ.get("AVOS_LLM_MODEL")
+    if llm_provider_env:
+        llm_data["provider"] = llm_provider_env
+    if llm_model_env:
+        llm_data["model"] = llm_model_env
+
+    # Align model with provider when the user did not set AVOS_LLM_MODEL.
+    # Defaults: openai -> gpt-4o, anthropic -> claude-sonnet-4-5-20250929.
+    provider = (llm_data.get("provider") or "openai").lower()
+    if not llm_model_env:
+        model = llm_data.get("model")
+        if provider == "openai":
+            if model is None or (isinstance(model, str) and model.startswith("claude-")):
+                llm_data["model"] = "gpt-4o"
+        elif provider == "anthropic" and (
+            model is None
+            or (
+                isinstance(model, str)
+                and (
+                    model.startswith("gpt-")
+                    or model.startswith("o1")
+                    or model.startswith("o3")
+                )
+            )
+        ):
+            llm_data["model"] = "claude-sonnet-4-5-20250929"
+    data["llm"] = llm_data
+
+
+def save_config(repo_root: Path, config_data: dict[str, Any]) -> None:
+    """Save configuration data to .avos/config.json atomically.
+
+    Creates the .avos directory if it doesn't exist. Uses atomic
+    write with restrictive permissions (0o600).
+
+    Args:
+        repo_root: Path to the repository root.
+        config_data: Configuration dictionary to persist.
+    """
+    avos_dir = repo_root / _AVOS_DIR
+    avos_dir.mkdir(parents=True, exist_ok=True)
+    config_path = avos_dir / _CONFIG_FILENAME
+    content = json.dumps(config_data, indent=2, sort_keys=True)
+    atomic_write(config_path, content, permissions=0o600)