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

avos_cli/utils/dotenv_load.py

@@ -0,0 +1,50 @@
+"""Layered ``.env`` loading shared by the CLI and HTTP clients.
+
+Order:
+    1. Current working directory (no override of existing process env).
+    2. Repository/package root ``.env`` beside ``avos_cli`` (override) so a
+       project-level token wins over cwd.
+    3. ``~/.avos/.env`` if present (no override of keys already set).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+_layers_loaded = False
+
+
+def repository_root_env_path() -> Path:
+    """Return the path to the ``.env`` file next to the ``avos_cli`` package tree.
+
+    For editable installs this is the project root; for site-packages installs
+    it is the directory above the installed ``avos_cli`` package.
+
+    Returns:
+        Absolute path whose basename is always ``.env``.
+    """
+    pkg_root = Path(__file__).resolve().parent.parent.parent
+    return pkg_root / ".env"
+
+
+def load_layers() -> None:
+    """Load layered dotenv files once per process."""
+    global _layers_loaded
+    if _layers_loaded:
+        return
+
+    load_dotenv()
+    try:
+        root_env = repository_root_env_path()
+        if root_env.exists():
+            load_dotenv(root_env, override=True)
+    except OSError:
+        pass
+
+    avos_user_env = Path.home() / ".avos" / ".env"
+    if avos_user_env.exists():
+        load_dotenv(avos_user_env, override=False)
+
+    _layers_loaded = True

avos_cli/utils/hashing.py

@@ -0,0 +1,22 @@
+"""Content hashing for artifact idempotency.
+
+Provides deterministic SHA-256 hashing of string content.
+Used by artifact builders to generate content_hash() values
+that enable duplicate detection during ingestion.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def content_hash(data: str) -> str:
+    """Compute a deterministic SHA-256 hex digest of the given string.
+
+    Args:
+        data: The string content to hash.
+
+    Returns:
+        64-character lowercase hex string of the SHA-256 digest.
+    """
+    return hashlib.sha256(data.encode("utf-8")).hexdigest()

avos_cli/utils/logger.py

@@ -0,0 +1,77 @@
+"""Structured logging with secret redaction for AVOS CLI.
+
+Provides a configured logger factory and a RedactionFilter that
+masks API keys, tokens, and other sensitive patterns in log output.
+Default level is INFO; DEBUG requires explicit --verbose opt-in.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+_SECRET_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"sk_[a-zA-Z0-9_]{10,}"),
+    re.compile(r"ghp_[a-zA-Z0-9]{10,}"),
+    re.compile(r"gho_[a-zA-Z0-9]{10,}"),
+    re.compile(r"ghs_[a-zA-Z0-9]{10,}"),
+    re.compile(r"ghu_[a-zA-Z0-9]{10,}"),
+    re.compile(r"github_pat_[a-zA-Z0-9_]{10,}"),
+]
+
+_REDACTED = "***REDACTED***"
+
+
+class RedactionFilter(logging.Filter):
+    """Logging filter that redacts known secret patterns from log messages.
+
+    Covers Avos API keys (sk_*), GitHub tokens (ghp_*, gho_*, ghs_*, ghu_*),
+    and GitHub fine-grained PATs (github_pat_*).
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Apply redaction to the log record message.
+
+        Args:
+            record: The log record to filter.
+
+        Returns:
+            Always True (record is never suppressed, only sanitized).
+        """
+        msg = record.getMessage()
+        redacted = msg
+        for pattern in _SECRET_PATTERNS:
+            redacted = pattern.sub(_REDACTED, redacted)
+        if redacted != msg:
+            record.msg = redacted
+            record.args = ()
+        return True
+
+
+def get_logger(component: str, level: int = logging.INFO) -> logging.Logger:
+    """Create a configured logger for an AVOS CLI component.
+
+    Args:
+        component: Component name (e.g. 'memory_client', 'git_client').
+        level: Logging level (default INFO).
+
+    Returns:
+        A Logger instance with redaction filter and structured formatter.
+    """
+    logger = logging.getLogger(f"avos.{component}")
+    logger.setLevel(level)
+
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setLevel(level)
+        formatter = logging.Formatter(
+            fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            datefmt="%Y-%m-%dT%H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    if not any(isinstance(f, RedactionFilter) for f in logger.filters):
+        logger.addFilter(RedactionFilter())
+
+    return logger

avos_cli/utils/output.py

@@ -0,0 +1,232 @@
+"""Terminal output formatting for AVOS CLI.
+
+Uses Rich for interactive terminals (tables, panels, trees, progress bars,
+colored status), with plain text fallback for piped/non-TTY output.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+from rich.theme import Theme
+from rich.tree import Tree
+
+_theme = Theme(
+    {
+        "success": "bold green",
+        "error": "bold red",
+        "warning": "bold yellow",
+        "info": "bold blue",
+        "dim": "dim",
+        "high": "bold red",
+        "medium": "bold yellow",
+        "low": "bold cyan",
+    }
+)
+
+console = Console(theme=_theme, stderr=True)
+
+
+class _NullProgress:
+    """No-op progress context manager for JSON mode (suppress progress bars)."""
+
+    def __enter__(self) -> _NullProgress:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        pass
+
+
+def is_interactive() -> bool:
+    """Check if stdout is connected to an interactive terminal."""
+    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def print_success(message: str) -> None:
+    """Print a success message in green."""
+    if is_interactive():
+        console.print("[success]\u2713[/success] ", end="")
+        console.print(message, markup=False)
+    else:
+        print(f"OK: {message}")
+
+
+def print_error(message: str) -> None:
+    """Print an error message in red."""
+    if is_interactive():
+        console.print("[error]\u2717[/error] ", end="")
+        console.print(message, markup=False)
+    else:
+        print(f"ERROR: {message}", file=sys.stderr)
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message in yellow."""
+    if is_interactive():
+        console.print("[warning]\u26a0[/warning] ", end="")
+        console.print(message, markup=False)
+    else:
+        print(f"WARN: {message}", file=sys.stderr)
+
+
+def print_info(message: str) -> None:
+    """Print an informational message."""
+    if is_interactive():
+        console.print("[info]\u2139[/info] ", end="")
+        console.print(message, markup=False)
+    else:
+        print(message)
+
+
+def print_json(
+    success: bool,
+    data: dict[str, object] | None = None,
+    error: dict[str, object] | None = None,
+) -> None:
+    """Emit strict JSON envelope for machine-readable output.
+
+    Per Q13: envelope is {"success": bool, "data": {...}, "error": {...}}.
+    When success=True, error is None; when success=False, data is None.
+
+    Args:
+        success: Whether the operation succeeded.
+        data: Command-specific payload (when success).
+        error: Error payload with code, message, hint, retryable (when not success).
+    """
+    envelope: dict[str, object] = {
+        "success": success,
+        "data": data,
+        "error": error,
+    }
+    print(json.dumps(envelope))
+
+
+def print_verbose(label: str, message: str, verbose: bool = False) -> None:
+    """Emit debug-level verbose line. Suppressed unless verbose is True.
+
+    Args:
+        label: Short label (e.g. "HTTP", "Config").
+        message: Debug message.
+        verbose: If False, does nothing.
+    """
+    if not verbose:
+        return
+    if is_interactive():
+        console.print(f"[dim][{label}] {message}[/dim]")
+    else:
+        print(f"[{label}] {message}", file=sys.stderr)
+
+
+def create_progress(description: str = "Processing...", suppress: bool = False) -> Progress | _NullProgress:
+    """Create a Rich progress bar for long-running operations.
+
+    When suppress=True (e.g. --json mode), returns a no-op progress that does nothing.
+
+    Args:
+        description: Text label for the progress bar.
+        suppress: If True, return no-op progress (for JSON output mode).
+
+    Returns:
+        A Rich Progress context manager (or no-op when suppress).
+    """
+    if suppress:
+        return _NullProgress()
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    )
+
+
+def render_table(
+    title: str,
+    columns: list[tuple[str, str]],
+    rows: list[list[str]],
+) -> None:
+    """Render a Rich table or plain-text equivalent.
+
+    Args:
+        title: Table title displayed above the table.
+        columns: List of (header_text, style) tuples.
+        rows: List of row data (each row is a list of strings matching columns).
+    """
+    if is_interactive():
+        table = Table(title=title, show_lines=False, pad_edge=True)
+        for header, style in columns:
+            table.add_column(header, style=style)
+        for row in rows:
+            table.add_row(*row)
+        console.print(table)
+    else:
+        print(f"\n{title}")
+        headers = [h for h, _ in columns]
+        print("  " + " | ".join(headers))
+        print("  " + "-+-".join("-" * len(h) for h in headers))
+        for row in rows:
+            print("  " + " | ".join(row))
+
+
+def render_panel(title: str, content: str, style: str = "info") -> None:
+    """Render a Rich panel or plain-text equivalent.
+
+    Args:
+        title: Panel title.
+        content: Panel body text.
+        style: Border color style name.
+    """
+    if is_interactive():
+        console.print(Panel(content, title=title, border_style=style, expand=False))
+    else:
+        print(f"\n--- {title} ---")
+        print(content)
+        print("---")
+
+
+def render_tree(label: str, children: list[tuple[str, list[str]]]) -> None:
+    """Render a Rich tree or plain-text indented equivalent.
+
+    Args:
+        label: Root label for the tree.
+        children: List of (branch_label, [leaf_labels]) tuples.
+    """
+    if is_interactive():
+        tree = Tree(f"[bold]{label}[/bold]")
+        for branch_label, leaves in children:
+            branch = tree.add(f"[info]{branch_label}[/info]")
+            for leaf in leaves:
+                branch.add(leaf)
+        console.print(tree)
+    else:
+        print(f"\n{label}")
+        for branch_label, leaves in children:
+            print(f"  {branch_label}")
+            for leaf in leaves:
+                print(f"    {leaf}")
+
+
+def render_kv_panel(title: str, pairs: list[tuple[str, str]], style: str = "info") -> None:
+    """Render a key-value panel (Rich table inside a panel, or plain text).
+
+    Args:
+        title: Panel title.
+        pairs: List of (key, value) tuples.
+        style: Border color style name.
+    """
+    if is_interactive():
+        table = Table(show_header=False, show_edge=False, pad_edge=False, box=None)
+        table.add_column("Key", style="bold")
+        table.add_column("Value")
+        for k, v in pairs:
+            table.add_row(k, v)
+        console.print(Panel(table, title=title, border_style=style, expand=False))
+    else:
+        print(f"\n--- {title} ---")
+        for k, v in pairs:
+            print(f"  {k}: {v}")
+
+

avos_cli/utils/sanitization_diagnostics.py

@@ -0,0 +1,81 @@
+"""Human-readable and JSON diagnostics when sanitization blocks LLM synthesis.
+
+Used when ``SanitizationResult.confidence_score`` is below the ask/history
+threshold so users understand why synthesis was skipped and how the score
+was affected.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from avos_cli.models.query import SanitizationResult
+
+_REDACTION_LABELS: dict[str, str] = {
+    "api_key": "API key-like strings (e.g. sk_…, AWS AKIA…)",
+    "token": "Bearer tokens or GitHub PAT-style tokens",
+    "credential": "password=/secret= style credential fields",
+    "private_key": "PEM private key blocks",
+    "pii": "email-shaped personal identifiers",
+    "injection": "prompt-injection-like phrases (redacted as [REDACTED_INJECTION])",
+}
+
+
+def explain_sanitization_gate(
+    result: SanitizationResult,
+    threshold: int,
+) -> tuple[str, list[str], dict[str, Any]]:
+    """Build headline, explanatory lines, and a JSON fragment for tooling.
+
+    Args:
+        result: Aggregate sanitization outcome for the retrieved artifacts.
+        threshold: Minimum confidence required to proceed to LLM synthesis.
+
+    Returns:
+        (headline for print_warning, detail lines for print_info,
+         dict to merge into JSON ``data``, e.g. ``{"sanitization": {...}}``).
+    """
+    score = result.confidence_score
+    types = list(result.redaction_types)
+
+    headline = (
+        f"Sanitization confidence is {score}/100 "
+        f"(minimum {threshold} required for LLM synthesis). "
+        "Showing sanitized evidence only, not an LLM summary."
+    )
+
+    lines: list[str] = [
+        "Why: Retrieved memory matched patterns we treat as sensitive or unsafe to "
+        "summarize (API keys, tokens, credentials, PEM private keys, email-shaped PII, "
+        "or prompt-injection-like text). Matching spans were replaced with "
+        "[REDACTED_*] placeholders. The confidence score reflects estimated remaining "
+        "risk after redaction; when it is below the threshold we skip synthesis.",
+    ]
+
+    if types:
+        described = [_REDACTION_LABELS.get(t, t.replace("_", " ")) for t in types]
+        lines.append("Categories flagged across retrieved snippets: " + "; ".join(described) + ".")
+    else:
+        lines.append(
+            "No aggregate redaction category list was recorded (unusual); "
+            "the low score may still reflect injection-pattern penalties."
+        )
+
+    if result.redaction_applied:
+        lines.append(
+            "At least one snippet had content redacted before display; "
+            "look for [REDACTED_API_KEY], [REDACTED_TOKEN], etc. in the evidence."
+        )
+
+    json_fragment: dict[str, Any] = {
+        "sanitization": {
+            "blocked_synthesis": True,
+            "confidence_score": score,
+            "required_minimum_confidence": threshold,
+            "redaction_applied": result.redaction_applied,
+            "redaction_types": types,
+            "fallback_reason": "safety_block",
+        }
+    }
+
+    return headline, lines, json_fragment

avos_cli/utils/time_helpers.py

@@ -0,0 +1,56 @@
+"""Time utilities for date calculations and TTL checks.
+
+Provides helpers for computing date windows (e.g. "180 days ago"),
+checking TTL expiry, and parsing ISO 8601 timestamps.
+All datetime operations use UTC.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+
+def days_ago(n: int) -> datetime:
+    """Return a UTC datetime representing N days before now.
+
+    Args:
+        n: Number of days to subtract from the current time.
+
+    Returns:
+        UTC-aware datetime N days in the past.
+    """
+    return datetime.now(tz=timezone.utc) - timedelta(days=n)
+
+
+def is_within_ttl(timestamp_iso: str, hours: int) -> bool:
+    """Check whether an ISO 8601 timestamp is within the last N hours.
+
+    Args:
+        timestamp_iso: ISO 8601 formatted timestamp string.
+        hours: TTL window in hours.
+
+    Returns:
+        True if the timestamp is within the last `hours` hours.
+    """
+    dt = parse_iso8601(timestamp_iso)
+    cutoff = datetime.now(tz=timezone.utc) - timedelta(hours=hours)
+    return dt >= cutoff
+
+
+def parse_iso8601(timestamp: str) -> datetime:
+    """Parse an ISO 8601 timestamp string into a UTC-aware datetime.
+
+    Handles 'Z' suffix, timezone offsets, and naive timestamps
+    (which are assumed to be UTC).
+
+    Args:
+        timestamp: ISO 8601 formatted string.
+
+    Returns:
+        Timezone-aware datetime in UTC.
+    """
+    cleaned = timestamp.replace("Z", "+00:00")
+    dt = datetime.fromisoformat(cleaned)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt