collab-runtime 0.2.9__py3-none-any.whl

scripts/cleanup.py

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""Artifact Cleanup Script.
+
+Removes generated files and directories produced by testing, linting,
+and formatting tools to keep the repository clean between runs.
+
+Can be run standalone or imported and called from other scripts.
+
+Usage:
+    python scripts/cleanup.py              # Clean test artifacts + coverage (default)
+    python scripts/cleanup.py --all        # Clean everything including caches
+    python scripts/cleanup.py --coverage   # Only coverage reporting
+                                           # (.coverage, htmlcov/, coverage/)
+    python scripts/cleanup.py --tests      # Only remove test runner output
+    python scripts/cleanup.py --packaging  # Only remove packaging outputs
+    python scripts/cleanup.py --caches     # Only tool caches (pycache, mypy, ruff)
+    python scripts/cleanup.py --dry-run    # Show what would be deleted without deleting
+    python scripts/cleanup.py --packaging --yes
+                                           # Non-interactive/CI removal
+"""
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+ROOT = Path(__file__).parent.parent
+
+# Directories/files that should NEVER be cleaned regardless of flags
+PROTECTED = {".venv", "venv", "node_modules", ".git", "instance", "test_data"}
+
+# ---------------------------------------------------------------------------
+# Artifact groups
+# ---------------------------------------------------------------------------
+
+# Coverage reporting and data files generated by pytest-cov
+COVERAGE_ARTIFACTS: List[str] = [
+    "htmlcov",  # pytest HTML coverage report (--cov-report=html)
+    "coverage",  # JS/Jest coverage directory (coverage/lcov.info, etc.)
+    ".coverage",  # pytest coverage data file
+    "coverage.xml",  # pytest XML coverage (--cov-report=xml)
+    "lcov.info",  # LCOV coverage format
+]
+
+# Glob patterns for scattered coverage files (e.g. parallel pytest runs)
+COVERAGE_GLOB_PATTERNS: List[str] = [
+    ".coverage.*",  # Parallel coverage data: .coverage.hostname.pid
+]
+
+# Test output artifacts
+TEST_OUTPUT_ARTIFACTS: List[str] = [
+    "test-results",  # Test traces/screenshots on failure
+    "playwright-report",  # Playwright HTML report
+    "blob-report",  # Playwright blob reporter output
+    "jscpd-report",  # JSCPD duplicate code report
+    ".jscpd",  # JSCPD internal cache
+]
+
+# Packaging-specific outputs (separate from test artifacts)
+PACKAGING_ARTIFACTS: List[str] = [
+    ".venv.verify",  # ephemeral venv used by packaging smoke tests
+    "dist",  # wheel and sdist output
+    "build",  # build workspace used during packaging
+    "pip-wheel-metadata",  # pip wheel metadata dir
+]
+
+# Glob patterns for scattered test output files
+TEST_OUTPUT_GLOB_PATTERNS: List[str] = [
+    "pytest-cache-files-*",  # Randomly named temporary directories from test runners
+]
+
+# Formatting tool artifacts
+FORMATTING_GLOB_PATTERNS: List[str] = [
+    "**/*.isorted",  # isort backup files created during formatting (recursive)
+]
+
+# Packaging-specific glob patterns
+PACKAGING_GLOB_PATTERNS: List[str] = [
+    "*.egg-info",  # packaging metadata directories
+]
+
+# Tool caches that speed up subsequent runs but pollute the repo visually.
+# These are optional (--caches / --all) since cleaning them slows next run.
+CACHE_ARTIFACTS: List[str] = [
+    ".pytest_cache",  # Pytest test cache
+    ".mypy_cache",  # Mypy type-check cache
+    ".ruff_cache",  # Ruff lint cache
+    ".bandit_cache",  # Bandit security scan cache
+]
+
+# Glob patterns for scattered cache files
+CACHE_GLOB_PATTERNS: List[str] = [
+    "**/__pycache__",  # Python bytecode cache (scattered everywhere)
+    "**/*.pyc",  # Compiled Python bytecode files
+    "**/*.pyo",  # Optimised Python bytecode files
+]
+
+
+def _is_protected(path: Path) -> bool:
+    """Return True if any part of the path is in the protected set."""
+    return any(part in PROTECTED for part in path.parts)
+
+
+def _remove(path: Path, dry_run: bool) -> Tuple[bool, str]:
+    """Delete a file or directory tree.
+
+    Args:
+        path: Path to remove.
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Tuple of (success, message).
+    """
+    if not path.exists():
+        return False, ""
+
+    kind = "dir" if path.is_dir() else "file"
+    label = f"  🗑  [{kind}] {path.relative_to(ROOT)}"
+
+    if dry_run:
+        return True, f"[DRY-RUN] {label}"
+
+    try:
+        if path.is_dir():
+            shutil.rmtree(path)
+        else:
+            path.unlink()
+        return True, label
+    except PermissionError as exc:
+        return False, f"  ⚠  Could not remove {path}: {exc}"
+    except OSError as exc:
+        return False, f"  ⚠  Could not remove {path}: {exc}"
+
+
+def _clean_items(names: List[str], dry_run: bool) -> int:
+    """Remove top-level artifacts by exact name relative to ROOT.
+
+    Args:
+        names: List of names to look for directly under ROOT.
+        dry_run: If True, only report.
+
+    Returns:
+        Number of items removed (or would-be removed).
+    """
+    count = 0
+    for name in names:
+        path = ROOT / name
+        if path.exists():
+            ok, msg = _remove(path, dry_run)
+            if msg:
+                print(msg)
+            if ok:
+                count += 1
+    return count
+
+
+def _clean_glob(patterns: List[str], dry_run: bool) -> int:
+    """Remove files/dirs matching glob patterns anywhere under ROOT.
+
+    Skips protected directories and .venv paths automatically.
+
+    Args:
+        patterns: List of glob patterns relative to ROOT.
+        dry_run: If True, only report.
+
+    Returns:
+        Number of items removed (or would-be removed).
+    """
+    count = 0
+    seen: set = set()
+
+    for pattern in patterns:
+        for match in sorted(ROOT.glob(pattern)):
+            if match in seen:
+                continue
+            seen.add(match)
+
+            try:
+                if _is_protected(match.relative_to(ROOT)):
+                    continue
+            except ValueError:
+                continue
+
+            ok, msg = _remove(match, dry_run)
+            if msg:
+                print(msg)
+            if ok:
+                count += 1
+
+    return count
+
+
+def clean_coverage(dry_run: bool = False) -> int:
+    """Remove coverage reporting and data files.
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    print("Cleaning coverage artifacts...")
+    total = 0
+    total += _clean_items(COVERAGE_ARTIFACTS, dry_run)
+    total += _clean_glob(COVERAGE_GLOB_PATTERNS, dry_run)
+    return total
+
+
+def clean_test_output(dry_run: bool = False) -> int:
+    """Remove test runner output artifacts.
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    print("Cleaning test output...")
+    total = 0
+    total += _clean_items(TEST_OUTPUT_ARTIFACTS, dry_run)
+    total += _clean_glob(TEST_OUTPUT_GLOB_PATTERNS, dry_run)
+    return total
+
+
+def clean_caches(dry_run: bool = False) -> int:
+    """Remove tool caches (__pycache__, .mypy_cache, .ruff_cache, etc.).
+
+    Note: Removing these makes the next tool run slightly slower because
+    caches must be rebuilt.
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    print("Cleaning tool caches...")
+    total = 0
+    total += _clean_items(CACHE_ARTIFACTS, dry_run)
+    total += _clean_glob(CACHE_GLOB_PATTERNS, dry_run)
+    return total
+
+
+def clean_default(dry_run: bool = False) -> int:
+    """Remove test artifacts, coverage reporting, and formatting artifacts (default
+    behaviour).
+
+    Keeps tool caches (.pytest_cache, .mypy_cache, etc.) intact so
+    subsequent runs stay fast.
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    return (
+        clean_coverage(dry_run) + clean_test_output(dry_run) + clean_formatting(dry_run)
+    )
+
+
+def clean_all(dry_run: bool = False) -> int:
+    """Remove everything: coverage, test output, formatting artifacts, AND tool caches.
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    return clean_default(dry_run) + clean_caches(dry_run)
+
+
+def clean_formatting(dry_run: bool = False) -> int:
+    """Remove formatting tool artifacts (*.isorted files from isort).
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    print("Cleaning formatting artifacts...")
+    return _clean_glob(FORMATTING_GLOB_PATTERNS, dry_run)
+
+
+def clean_packaging(dry_run: bool = False) -> int:
+    """Remove packaging build outputs: dist/, build/, wheel metadata, and egg-info dirs.
+
+    Args:
+        dry_run: If True, only report what would be removed.
+
+    Returns:
+        Total number of items cleaned.
+    """
+    print("Cleaning packaging artifacts...")
+    total = 0
+    total += _clean_items(PACKAGING_ARTIFACTS, dry_run)
+    total += _clean_glob(PACKAGING_GLOB_PATTERNS, dry_run)
+    return total
+
+
+def main() -> int:
+    """Entry point for standalone execution."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Remove generated artifacts from testing, linting, and formatting tools."
+        )
+    )
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        "--all",
+        action="store_true",
+        help="Clean everything including tool caches (__pycache__, .mypy_cache, etc.)",
+    )
+    group.add_argument(
+        "--coverage",
+        action="store_true",
+        help="Only remove coverage reporting and data files",
+    )
+    group.add_argument(
+        "--tests",
+        action="store_true",
+        help="Only remove test runner output",
+    )
+    group.add_argument(
+        "--packaging",
+        action="store_true",
+        help="Remove packaging artifacts (dist, build, wheel metadata)",
+    )
+    group.add_argument(
+        "--caches",
+        action="store_true",
+        help="Only remove tool caches (__pycache__, .mypy_cache, .ruff_cache, etc.)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deleted without actually deleting anything",
+    )
+    parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="Assume yes to prompts (non-interactive/CI friendly)",
+    )
+
+    args = parser.parse_args()
+
+    print("\n" + "=" * 60)
+    mode = "[DRY-RUN] " if args.dry_run else ""
+    print(f"{mode}🧹 ARTIFACT CLEANUP")
+    print("=" * 60)
+
+    if args.all:
+        count = clean_all(args.dry_run)
+        label = "all artifacts (including caches)"
+    elif args.coverage:
+        count = clean_coverage(args.dry_run)
+        label = "coverage artifacts"
+    elif args.tests:
+        count = clean_test_output(args.dry_run)
+        label = "test output artifacts"
+    elif args.packaging:
+        # Require confirmation for packaging removal (unless --dry-run/--yes)
+        if not args.dry_run and not args.yes:
+            reply = (
+                input("Remove packaging outputs (dist/, build/, egg-info)? [y/N]: ")
+                .strip()
+                .lower()
+            )
+            if reply not in ("y", "yes"):
+                print("Aborted by user.")
+                return 2
+        count = clean_packaging(args.dry_run)
+        label = "packaging artifacts"
+    elif args.caches:
+        count = clean_caches(args.dry_run)
+        label = "tool caches"
+    else:
+        count = clean_default(args.dry_run)
+        label = "test artifacts + coverage"
+
+    print()
+    if count:
+        verb = "Would remove" if args.dry_run else "Removed"
+        print(f"✅ {verb} {count} item(s) from {label}.")
+    else:
+        print(f"✨ Nothing to clean in {label}.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/collab_git_hook.py

@@ -0,0 +1,190 @@
+"""Git hook helpers for collab lock lifecycle integration."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+from dotenv import load_dotenv
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+SRC_ROOT = PROJECT_ROOT / "src"
+
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+load_dotenv(PROJECT_ROOT / ".env")
+
+
+def _git_output(*args: str) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=PROJECT_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            result.stderr.strip() or result.stdout.strip() or "git failed"
+        )
+    return result.stdout.strip()
+
+
+def _get_staged_files() -> list[str]:
+    output = _git_output("diff", "--cached", "--name-only", "--diff-filter=ACMR")
+    return [line.strip() for line in output.splitlines() if line.strip()]
+
+
+def _read_pid_file() -> Optional[int]:
+    from src.lock_client import PID_FILE
+
+    pid_path = Path(PID_FILE)
+    if not pid_path.exists():
+        return None
+
+    try:
+        raw = pid_path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+
+    if not raw:
+        return None
+
+    if raw.startswith("{"):
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            return None
+        pid = payload.get("pid")
+        return pid if isinstance(pid, int) else None
+
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+def _pid_is_running(pid: int) -> bool:
+    try:
+        import psutil  # type: ignore
+
+        return bool(psutil.pid_exists(pid))
+    except Exception:
+        try:
+            os.kill(pid, 0)
+        except PermissionError:
+            return True
+        except OSError:
+            return False
+        return True
+
+
+def _watcher_pid() -> Optional[int]:
+    pid = _read_pid_file()
+    if pid is None:
+        return None
+    return pid if _pid_is_running(pid) else None
+
+
+def acquire_staged() -> int:
+    from src.lock_client import LockClient
+
+    staged_files = _get_staged_files()
+    if not staged_files:
+        return 0
+
+    watcher_pid = _watcher_pid()
+    if watcher_pid is not None:
+        print(
+            "[collab] Watcher running "
+            f"(PID: {watcher_pid}) — skipping pre-commit lock acquisition.",
+            file=sys.stderr,
+        )
+        return 0
+
+    try:
+        client = LockClient()
+        ok, failed, _message = client.acquire_multiple(
+            staged_files, reason="pre-commit"
+        )
+    except Exception as exc:
+        print(f"[collab] Warning: lock check failed: {exc}", file=sys.stderr)
+        return 1 if os.getenv("LOCK_STRICT", "0") == "1" else 0
+
+    if ok:
+        print(
+            f"[collab] Locks acquired for {len(staged_files)} staged file(s).",
+            file=sys.stderr,
+        )
+        return 0
+
+    print("[collab] Commit blocked due to lock conflicts:", file=sys.stderr)
+    for file_path in failed:
+        try:
+            status = client.get_lock_status(file_path)
+        except Exception:
+            status = {}
+        owner = status.get("locked_by") or status.get("developer_id") or "unknown"
+        print(f"  - {file_path} (locked by @{owner})", file=sys.stderr)
+    return 1
+
+
+def release_all() -> int:
+    from src.lock_client import LockClient
+
+    try:
+        client = LockClient()
+        released = client.release_all()
+    except Exception as exc:
+        print(f"[collab] Warning: lock cleanup failed: {exc}", file=sys.stderr)
+        return 0
+
+    print(f"[collab] Released {released} lock(s).", file=sys.stderr)
+    return 0
+
+
+def validate_and_release() -> int:
+    """Run quick validation, then release locks only on success."""
+    validate_script = PROJECT_ROOT / "scripts" / "validate_code.py"
+    result = subprocess.run(
+        [sys.executable, str(validate_script), "--quick"],
+        cwd=PROJECT_ROOT,
+        stdout=subprocess.DEVNULL,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            "[collab] Pre-push validation failed — keeping locks active.",
+            file=sys.stderr,
+        )
+        return result.returncode
+    return release_all()
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print(
+            "Usage: python scripts/collab_git_hook.py "
+            "<acquire-staged|release-all|validate-and-release>"
+        )
+        return 2
+
+    command = sys.argv[1]
+    if command == "acquire-staged":
+        return acquire_staged()
+    if command == "release-all":
+        return release_all()
+    if command == "validate-and-release":
+        return validate_and_release()
+
+    print(f"Unknown command: {command}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())