droidguard 2.0.0__py3-none-any.whl

droidguard/__init__.py

@@ -0,0 +1,17 @@
+"""DroidGuard — Deterministic Android Verification & AI Agent Governance Engine.
+
+Provides fail-closed tool inspection, multi-agent review consensus, supervised
+Gradle execution, multi-locale parity validation, Room schema diff checks,
+Jetpack Compose stability analysis, and unified PM gateways.
+"""
+
+__version__ = "2.0.0"
+__author__ = "DroidGuard Contributors"
+__license__ = "Apache-2.0"
+
+from droidguard._errors import DroidGuardError
+
+__all__ = [
+    "DroidGuardError",
+    "__version__",
+]

droidguard/__main__.py

@@ -0,0 +1,7 @@
+"""Execution entrypoint for `python -m droidguard`."""
+
+from droidguard.cli.main import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()
+

droidguard/_compat.py

@@ -0,0 +1,176 @@
+"""Cross-platform compatibility layer for DroidGuard.
+
+Handles operating system differences for process trees (Win32 Job Objects on Windows,
+process groups on Unix), atomic file writes, filesystem permissions, and terminal coloring.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+def is_windows() -> bool:
+    """Return True if running on Windows."""
+    return sys.platform == "win32" or sys.platform == "cygwin" or os.name == "nt"
+
+
+def is_macos() -> bool:
+    """Return True if running on macOS (Darwin)."""
+    return sys.platform == "darwin"
+
+
+def is_linux() -> bool:
+    """Return True if running on Linux."""
+    return sys.platform.startswith("linux")
+
+
+def make_executable(path: Path | str) -> None:
+    """Set the executable permission bit (0o755) on POSIX systems safely.
+
+    On Windows, this is a safe no-op.
+    """
+    target = Path(path)
+    if not is_windows() and target.exists():
+        try:
+            current_mode = target.stat().st_mode
+            target.chmod(current_mode | 0o111 | 0o700)
+        except OSError:
+            pass
+
+
+def atomic_write_text(path: Path | str, content: str, encoding: str = "utf-8") -> None:
+    """Write text atomically using a temporary file and os.replace."""
+    target = Path(path).resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    temp_dir = target.parent
+    fd, tmp_path = tempfile.mkstemp(prefix=f".{target.name}.tmp_", dir=temp_dir, text=True)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding, newline="") as f:
+            f.write(content)
+        os.replace(tmp_path, target)
+    except Exception:
+        if os.path.exists(tmp_path):
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+        raise
+
+
+def atomic_write_bytes(path: Path | str, content: bytes) -> None:
+    """Write binary data atomically using a temporary file and os.replace."""
+    target = Path(path).resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    temp_dir = target.parent
+    fd, tmp_path = tempfile.mkstemp(prefix=f".{target.name}.tmp_", dir=temp_dir, text=False)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(content)
+        os.replace(tmp_path, target)
+    except Exception:
+        if os.path.exists(tmp_path):
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+        raise
+
+
+def safe_rmtree(path: Path | str) -> None:
+    """Safely remove a directory tree, ignoring missing errors."""
+    target = Path(path)
+    if target.exists():
+        shutil.rmtree(target, ignore_errors=True)
+
+
+class Win32JobObject:
+    """Context manager / helper for Windows Win32 Job Objects."""
+
+    def __init__(self) -> None:
+        self._job_handle: Any = None
+        if is_windows():
+            try:
+                import ctypes
+                import ctypes.wintypes
+
+                kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+                self._create_job = kernel32.CreateJobObjectW
+                self._create_job.argtypes = [ctypes.c_void_p, ctypes.c_wchar_p]
+                self._create_job.restype = ctypes.wintypes.HANDLE
+
+                self._assign_job = kernel32.AssignProcessToJobObject
+                self._assign_job.argtypes = [ctypes.wintypes.HANDLE, ctypes.wintypes.HANDLE]
+                self._assign_job.restype = ctypes.wintypes.BOOL
+
+                self._terminate_job = kernel32.TerminateJobObject
+                self._terminate_job.argtypes = [ctypes.wintypes.HANDLE, ctypes.wintypes.UINT]
+                self._terminate_job.restype = ctypes.wintypes.BOOL
+
+                self._close_handle = kernel32.CloseHandle
+                self._close_handle.argtypes = [ctypes.wintypes.HANDLE]
+                self._close_handle.restype = ctypes.wintypes.BOOL
+
+                self._job_handle = self._create_job(None, None)
+            except Exception:
+                self._job_handle = None
+
+    def assign_process(self, process_handle: int) -> bool:
+        """Assign a Windows process handle to this job object."""
+        if is_windows() and self._job_handle and self._assign_job:
+            try:
+                return bool(self._assign_job(self._job_handle, process_handle))
+            except Exception:
+                return False
+        return False
+
+    def terminate(self, exit_code: int = 1) -> bool:
+        """Terminate all processes assigned to this job object."""
+        if is_windows() and self._job_handle and self._terminate_job:
+            try:
+                return bool(self._terminate_job(self._job_handle, exit_code))
+            except Exception:
+                return False
+        return False
+
+    def close(self) -> None:
+        """Close the job object handle."""
+        if is_windows() and self._job_handle and self._close_handle:
+            try:
+                self._close_handle(self._job_handle)
+            except Exception:
+                pass
+            finally:
+                self._job_handle = None
+
+
+def configure_utf8_streams() -> None:
+    """Configure sys.stdout and sys.stderr to use UTF-8 with fallback replacement to prevent Windows CP1252 UnicodeEncodeErrors."""
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+
+def kill_posix_process_group(pid: int) -> None:
+    """Safely terminate a POSIX process group without crashing on non-POSIX platforms."""
+    if not is_windows():
+        try:
+            getpgid = getattr(os, "getpgid", None)
+            killpg = getattr(os, "killpg", None)
+            if getpgid and killpg:
+                pgid = getpgid(pid)
+                killpg(pgid, signal.SIGTERM)
+        except Exception:
+            pass
+
+

droidguard/_errors.py

@@ -0,0 +1,63 @@
+"""Structured Exception Hierarchy for DroidGuard.
+
+Every exception raised by DroidGuard derives from DroidGuardError.
+All error messages must be actionable, clear, and descriptive.
+"""
+
+from __future__ import annotations
+
+
+class DroidGuardError(Exception):
+    """Base exception for all DroidGuard errors."""
+
+    def __init__(self, message: str, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+    def __str__(self) -> str:
+        if self.hint:
+            return f"{self.message}\n  Hint: {self.hint}"
+        return self.message
+
+
+class ConfigError(DroidGuardError):
+    """Raised when droidguard.toml is invalid, missing required keys, or corrupted."""
+
+
+class SafetyViolation(DroidGuardError):
+    """Raised when an AI tool call attempts an unsafe or prohibited command.
+
+    Fails closed (deny-by-default) to protect git history, hardware, and developer data.
+    """
+
+
+class CheckError(DroidGuardError):
+    """Raised when a static or architectural check fails."""
+
+
+class CheckSkipped(DroidGuardError):
+    """Raised/used when an optional check is skipped due to missing project components.
+
+    Not a failure; used for graceful degradation.
+    """
+
+
+class BuildError(DroidGuardError):
+    """Raised when a Gradle build or compilation task fails."""
+
+
+class PMError(DroidGuardError):
+    """Raised when a Project Management integration (Zoho, Jira, Linear, GitHub) fails."""
+
+
+class DeviceError(DroidGuardError):
+    """Raised when an ADB or device interaction fails."""
+
+
+class StateError(DroidGuardError):
+    """Raised when an internal state, SQLite, or lock operation fails."""
+
+
+class NonAndroidProjectError(DroidGuardError):
+    """Raised when a command is executed in a directory that is not an Android project."""

droidguard/_logging.py

@@ -0,0 +1,161 @@
+"""Structured Logging and Terminal Output for DroidGuard.
+
+Follows Rule 17 (Unicode & UTF-8 Safety) and Rule 18 (Unified Logging).
+Handles legacy Windows console code pages (cp1252, cp437) gracefully with ASCII fallbacks.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import TextIO
+
+from droidguard._compat import is_windows
+
+_LOG_FORMAT = "[%(asctime)s] [%(levelname)s] [%(name)s]: %(message)s"
+_DATE_FORMAT = "%H:%M:%S"
+
+# ANSI Colors
+_COLOR_RESET = "\033[0m"
+_COLOR_BOLD = "\033[1m"
+_COLOR_RED = "\033[31m"
+_COLOR_GREEN = "\033[32m"
+_COLOR_YELLOW = "\033[33m"
+_COLOR_BLUE = "\033[34m"
+_COLOR_CYAN = "\033[36m"
+_COLOR_GRAY = "\033[90m"
+
+
+def _can_encode_symbol(symbol: str, stream: TextIO) -> bool:
+    """Return True if the stream can encode the given symbol."""
+    encoding = getattr(stream, "encoding", None) or "utf-8"
+    try:
+        symbol.encode(encoding)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def _safe_print(text: str, stream: TextIO | None = None) -> None:
+    """Safely print text to stream with automatic fallback if encoding fails."""
+    target_stream = stream or sys.stdout
+    encoding = getattr(target_stream, "encoding", None) or "utf-8"
+    try:
+        target_stream.write(text + "\n")
+        target_stream.flush()
+    except UnicodeEncodeError:
+        safe_bytes = (text + "\n").encode(encoding, errors="replace")
+        target_stream.buffer.write(safe_bytes)
+        target_stream.buffer.flush()
+
+
+def _supports_color(stream: TextIO) -> bool:
+    """Return True if the stream supports ANSI escape codes."""
+    if os.environ.get("NO_COLOR") or os.environ.get("DROIDGUARD_NO_COLOR"):
+        return False
+    if not hasattr(stream, "isatty") or not stream.isatty():
+        return False
+    if is_windows():
+        return "WT_SESSION" in os.environ or "ANSICON" in os.environ or "TERM" in os.environ
+    return True
+
+
+class DroidGuardFormatter(logging.Formatter):
+    """Custom logging formatter with optional terminal colors."""
+
+    def __init__(self, use_color: bool = True) -> None:
+        super().__init__(fmt=_LOG_FORMAT, datefmt=_DATE_FORMAT)
+        self.use_color = use_color
+
+    def format(self, record: logging.LogRecord) -> str:
+        formatted = super().format(record)
+        if not self.use_color:
+            return formatted
+
+        if record.levelno >= logging.ERROR:
+            return f"{_COLOR_RED}{formatted}{_COLOR_RESET}"
+        if record.levelno >= logging.WARNING:
+            return f"{_COLOR_YELLOW}{formatted}{_COLOR_RESET}"
+        if record.levelno >= logging.INFO:
+            return f"{_COLOR_CYAN}{formatted}{_COLOR_RESET}"
+        return f"{_COLOR_GRAY}{formatted}{_COLOR_RESET}"
+
+
+def setup_logging(verbose: bool = False, log_file: str | None = None) -> None:
+    """Configure root logger for DroidGuard."""
+    # Ensure UTF-8 stream reconfiguration if supported
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        if stream and hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+    level = logging.DEBUG if verbose else logging.INFO
+    root = logging.getLogger("droidguard")
+    root.setLevel(level)
+    root.handlers.clear()
+
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(level)
+    console_handler.setFormatter(DroidGuardFormatter(use_color=_supports_color(sys.stderr)))
+    root.addHandler(console_handler)
+
+    if log_file:
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(DroidGuardFormatter(use_color=False))
+        root.addHandler(file_handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a scoped logger under droidguard.* namespace."""
+    if not name.startswith("droidguard"):
+        name = f"droidguard.{name}"
+    return logging.getLogger(name)
+
+
+def print_success(message: str) -> None:
+    """Print user-facing green success message."""
+    color = _COLOR_GREEN if _supports_color(sys.stdout) else ""
+    reset = _COLOR_RESET if _supports_color(sys.stdout) else ""
+    sym = "✓" if _can_encode_symbol("✓", sys.stdout) else "[+]"
+    _safe_print(f"{color}{sym} {message}{reset}", sys.stdout)
+
+
+def print_error(message: str) -> None:
+    """Print user-facing red error message."""
+    color = _COLOR_RED if _supports_color(sys.stderr) else ""
+    reset = _COLOR_RESET if _supports_color(sys.stderr) else ""
+    sym = "✗" if _can_encode_symbol("✗", sys.stderr) else "[-]"
+    _safe_print(f"{color}{sym} {message}{reset}", sys.stderr)
+
+
+def print_warning(message: str) -> None:
+    """Print user-facing yellow warning message."""
+    color = _COLOR_YELLOW if _supports_color(sys.stdout) else ""
+    reset = _COLOR_RESET if _supports_color(sys.stdout) else ""
+    sym = "!" if _can_encode_symbol("!", sys.stdout) else "[!]"
+    _safe_print(f"{color}{sym} {message}{reset}", sys.stdout)
+
+
+def print_info(message: str) -> None:
+    """Print user-facing blue info message."""
+    color = _COLOR_BLUE if _supports_color(sys.stdout) else ""
+    reset = _COLOR_RESET if _supports_color(sys.stdout) else ""
+    sym = "ℹ" if _can_encode_symbol("ℹ", sys.stdout) else "[*]"
+    _safe_print(f"{color}{sym} {message}{reset}", sys.stdout)
+
+
+def print_banner() -> None:
+    """Print the DroidGuard banner to stdout."""
+    bold = _COLOR_BOLD if _supports_color(sys.stdout) else ""
+    green = _COLOR_GREEN if _supports_color(sys.stdout) else ""
+    reset = _COLOR_RESET if _supports_color(sys.stdout) else ""
+    shield = "🛡️" if _can_encode_symbol("🛡️", sys.stdout) else "[DG]"
+    _safe_print(
+        f"{bold}{green}{shield} DroidGuard 2.0{reset} — Universal Android Engineering Governance & Verification",
+        sys.stdout,
+    )

droidguard/adapters/__init__.py

@@ -0,0 +1,24 @@
+"""DroidGuard IDE and AI Assistant Adapters Package."""
+
+from droidguard.adapters.antigravity import AntigravityAdapter
+from droidguard.adapters.base import AdapterSyncResult, BaseAdapter
+from droidguard.adapters.claude import ClaudeAdapter
+from droidguard.adapters.cline import ClineAdapter
+from droidguard.adapters.codex import CodexAdapter
+from droidguard.adapters.copilot import CopilotAdapter
+from droidguard.adapters.cursor import CursorAdapter
+from droidguard.adapters.qwen import QwenAdapter
+from droidguard.adapters.windsurf import WindsurfAdapter
+
+__all__ = [
+    "AdapterSyncResult",
+    "AntigravityAdapter",
+    "BaseAdapter",
+    "ClaudeAdapter",
+    "ClineAdapter",
+    "CodexAdapter",
+    "CopilotAdapter",
+    "CursorAdapter",
+    "QwenAdapter",
+    "WindsurfAdapter",
+]

droidguard/adapters/antigravity.py

@@ -0,0 +1,54 @@
+"""Antigravity Sidecar and Agent Environment Adapter for DroidGuard."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from droidguard._compat import atomic_write_text
+from droidguard.adapters.base import AdapterSyncResult, BaseAdapter
+from droidguard.config.schema import DroidGuardConfig
+
+
+class AntigravityAdapter(BaseAdapter):
+    """Adapter for Google Antigravity AI agent platform."""
+
+    name: str = "antigravity"
+
+    def sync(self, project_root: Path, config: DroidGuardConfig) -> AdapterSyncResult:
+        created: list[Path] = []
+        updated: list[Path] = []
+
+        agents_dir = project_root / ".agents"
+        rules_dir = agents_dir / "rules"
+        rules_dir.mkdir(parents=True, exist_ok=True)
+
+        rules_file = rules_dir / "droidguard-rules.md"
+        content = f"""# DroidGuard Agent Governance Rules for {config.project.name}
+
+## 1. Non-Negotiable Governance & Security
+- **Git Authority**: AI agents are strictly forbidden from executing mutating Git commands (`commit`, `push`, `reset`, `rebase`, `checkout -b`). Only the human developer holds Git mutation authority.
+- **Fail-Closed Verification**: Before declaring tasks ready for review, execute `dg preflight`.
+- **Review Quorum**: All builds and release gates require {config.review.leaf_count}-leaf subagent consensus (`dg verify`).
+- **PM Authority**: AI agents may only advance tasks to 'Ready for QA'. Marking tasks as 'Done' or 'Solved' is prohibited.
+
+## 2. Android Architecture & Quality Standards
+- **UI Toolkit**: {config.project.ui_toolkit.upper()} (Enforce @Immutable on Compose state models).
+- **DI Framework**: {config.project.di_framework.capitalize()}.
+- **Multi-Locale Parity**: All string resources must be added to `{config.checks.strings.base_locale}/strings.xml` and translated in all target locales.
+- **Room Database**: Any schema change in `schemas/` must have a corresponding `Migration` class.
+- **Performance & ANR**: Never use `runBlocking` or blocking `Thread.sleep()` in production code.
+"""
+        is_update = rules_file.exists()
+        atomic_write_text(rules_file, content)
+
+        if is_update:
+            updated.append(rules_file)
+        else:
+            created.append(rules_file)
+
+        return AdapterSyncResult(
+            adapter_name=self.name,
+            files_created=created,
+            files_updated=updated,
+            message=f"Synchronized Antigravity rules at {rules_file.name}.",
+        )

droidguard/adapters/base.py

@@ -0,0 +1,28 @@
+"""Base Adapter Protocol and Model for AI IDE and Assistant Integrations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from droidguard.config.schema import DroidGuardConfig
+
+
+@dataclass
+class AdapterSyncResult:
+    adapter_name: str
+    files_created: list[Path]
+    files_updated: list[Path]
+    is_success: bool = True
+    message: str = ""
+
+
+class BaseAdapter(Protocol):
+    """Protocol for all IDE / Agent environment adapters."""
+
+    name: str
+
+    def sync(self, project_root: Path, config: DroidGuardConfig) -> AdapterSyncResult:
+        """Generate and synchronize rule and config files for this environment."""
+        ...

droidguard/adapters/claude.py

@@ -0,0 +1,60 @@
+"""Claude Code CLI Adapter for DroidGuard.
+
+Generates `CLAUDE.md` with deterministic build, preflight, and safety instructions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from droidguard._compat import atomic_write_text
+from droidguard.adapters.base import AdapterSyncResult, BaseAdapter
+from droidguard.config.schema import DroidGuardConfig
+
+
+class ClaudeAdapter(BaseAdapter):
+    """Adapter for Anthropic Claude Code CLI."""
+
+    name: str = "claude"
+
+    def sync(self, project_root: Path, config: DroidGuardConfig) -> AdapterSyncResult:
+        created: list[Path] = []
+        updated: list[Path] = []
+
+        claude_file = project_root / "CLAUDE.md"
+        content = f"""# CLAUDE.md — Android Engineering Guidelines for {config.project.name}
+
+## 🛡️ DroidGuard Governance & Safety Policy
+- **Git Mutations Blocked**: Do NOT execute `git commit`, `git push`, `git checkout -b`, or `git reset`. The developer commits code.
+- **Preflight Verification**: Always run `dg preflight` before finishing tasks.
+- **Verification Consensus**: Run `dg verify` to inspect the package hash and consensus quorum.
+- **Delivery Pipeline**: Use `dg deliver` to execute supervised build and post QA reports.
+
+## 🛠️ Build & Verification Commands
+- Run Preflight Checks: `dg preflight`
+- Verify Quorum: `dg verify`
+- Supervised Gradle Build: `./gradlew assembleDebug`
+- Supervised Unit Tests: `./gradlew testDebugUnitTest`
+- Android Lint: `./gradlew lintDebug`
+
+## 📐 Architecture & Quality Rules
+- **UI Toolkit**: {config.project.ui_toolkit.upper()} (Annotate MVI state data classes with `@Immutable`).
+- **Dependency Injection**: {config.project.di_framework.capitalize()}.
+- **String Parity**: Add string keys to base `values/strings.xml` and target `values-*/strings.xml`.
+- **Room Migrations**: Keep schema versions contiguous (1.json -> 2.json) and define Migration objects.
+- **Performance**: Prohibit `runBlocking`, blocking I/O on Main thread, and holding Context in ViewModels.
+"""
+        is_update = claude_file.exists()
+        atomic_write_text(claude_file, content)
+
+        if is_update:
+            updated.append(claude_file)
+        else:
+            created.append(claude_file)
+
+        return AdapterSyncResult(
+            adapter_name=self.name,
+            files_created=created,
+            files_updated=updated,
+            message=f"Synchronized Claude Code guidelines at {claude_file.name}.",
+        )

droidguard/adapters/cline.py

@@ -0,0 +1,38 @@
+"""Cline and Roo Code AI Adapter for DroidGuard."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from droidguard._compat import atomic_write_text
+from droidguard.adapters.base import AdapterSyncResult, BaseAdapter
+from droidguard.config.schema import DroidGuardConfig
+
+
+class ClineAdapter(BaseAdapter):
+    """Adapter for Cline and Roo Code AI assistants."""
+
+    name: str = "cline"
+
+    def sync(self, project_root: Path, config: DroidGuardConfig) -> AdapterSyncResult:
+        created: list[Path] = []
+        updated: list[Path] = []
+
+        rules_file = project_root / ".clinerules"
+        content = f"""# Cline & Roo Rules for {config.project.name}
+
+- Human developer holds exclusive Git commit authority (no git commits from AI).
+- Run `dg preflight` to verify changes before completing tasks.
+- Architecture: UI={config.project.ui_toolkit.upper()}, DI={config.project.di_framework.capitalize()}.
+- No runBlocking or Thread.sleep in production code.
+"""
+        is_update = rules_file.exists()
+        atomic_write_text(rules_file, content)
+        (updated if is_update else created).append(rules_file)
+
+        return AdapterSyncResult(
+            adapter_name=self.name,
+            files_created=created,
+            files_updated=updated,
+            message=f"Synchronized Cline rules at {rules_file.name}.",
+        )