collab-runtime 0.2.9__py3-none-any.whl

src/logging_config.py

@@ -0,0 +1,259 @@
+"""Centralized logging helpers for the collab utilities.
+
+This module configures a repository-scoped logs directory at `logs/` and provides an
+idempotent helper to wire FileHandlers and a console handler without producing duplicate
+handlers when called multiple times (useful for import-time setup in CLI tools and long-
+running daemons).
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import time
+from logging.handlers import RotatingFileHandler
+from typing import Optional
+
+DEFAULT_FORMAT = "[%(asctime)s] %(levelname)s %(name)s: %(message)s"
+DEFAULT_DATEFMT = "%Y-%m-%d %H:%M:%S"
+DEFAULT_LOG_MAX_BYTES = 5 * 1024 * 1024
+DEFAULT_LOG_BACKUP_COUNT = 5
+DEFAULT_LOG_RETENTION_DAYS = 5
+
+
+def _read_clean_env_path(name: str) -> Optional[str]:
+    """Return a sanitized env path value, ignoring empty/comment-only values."""
+    raw = os.getenv(name)
+    if raw is None:
+        return None
+    cleaned = raw.strip()
+    if not cleaned:
+        return None
+    if "#" in cleaned:
+        cleaned = cleaned.split("#", 1)[0].strip()
+    if not cleaned or cleaned.startswith("#"):
+        return None
+    return cleaned
+
+
+def _resolve_runtime_root() -> str:
+    """Resolve runtime root for the current project.
+
+    Preference order:
+      1. COLLAB_HOME env override
+      2. COLLAB_STATE_DIR env override (backwards compatibility/test isolation)
+      3. Fallback to project root
+    """
+    home_override = _read_clean_env_path("COLLAB_HOME")
+    if home_override:
+        return os.path.abspath(home_override)
+
+    state_override = _read_clean_env_path("COLLAB_STATE_DIR")
+    if state_override:
+        return os.path.abspath(state_override)
+
+    project_root = _read_clean_env_path("COLLAB_PROJECT_ROOT") or os.path.abspath(
+        os.getcwd()
+    )
+    return project_root
+
+
+def _ensure_dir(path: str) -> None:
+    try:
+        os.makedirs(path, exist_ok=True)
+    except Exception:
+        # Best-effort: if we cannot create a logs directory, don't raise here
+        # to avoid breaking CLI entrypoints. Upstream callers will still see
+        # console output.
+        pass
+
+
+def _is_test_mode() -> bool:
+    return (
+        os.getenv("COLLAB_TEST_MODE") == "1"
+        or os.getenv("TESTING") == "1"
+        or "PYTEST_CURRENT_TEST" in os.environ
+    )
+
+
+def _prune_old_log_files(
+    log_dir: str,
+    active_log_name: str,
+    *,
+    retention_days: int = DEFAULT_LOG_RETENTION_DAYS,
+    now: Optional[float] = None,
+) -> None:
+    """Delete expired rotated log files for the active log family.
+
+    The current active log file is never deleted here, even if its mtime is old.
+    Rotation limits file size; this pruning step bounds total on-disk lifetime.
+    """
+    if retention_days <= 0:
+        return
+
+    cutoff = (time.time() if now is None else now) - (retention_days * 24 * 60 * 60)
+    active_path = os.path.abspath(os.path.join(log_dir, active_log_name))
+    try:
+        entries = list(os.scandir(log_dir))
+    except OSError:
+        return
+
+    for entry in entries:
+        try:
+            if not entry.is_file():
+                continue
+            if not entry.name.startswith(active_log_name):
+                continue
+
+            entry_path = os.path.abspath(entry.path)
+            if entry_path == active_path:
+                continue
+
+            if entry.stat().st_mtime < cutoff:
+                os.remove(entry.path)
+        except OSError:
+            continue
+
+
+def _resolve_log_dir(collab_dir: Optional[str]) -> str:
+    """Resolve the log directory for the current collab runtime.
+
+    Logs always live under ``<runtime_root>/logs/`` so they are persistent and
+    discoverable regardless of the test isolation environment.  COLLAB_STATE_DIR
+    isolates *process-state* artifacts (PID files, lock files) but must not
+    redirect log files, because the temp dir it points to is cleaned up after each
+    test session, making the logs ephemeral and invisible to the developer.
+
+    File-handle safety for test mode is handled by:
+    - the ``atexit.register(close_collab_logging)`` call in this module, and
+    - the autouse ``_close_collab_logging_after_each_test`` fixture in
+    `tests/conftest.py`.
+    """
+    if collab_dir:
+        base = collab_dir
+    else:
+        base = _resolve_runtime_root()
+    return os.path.join(base, "logs")
+
+
+def _close_collab_file_handlers() -> None:
+    """Close and detach all file handlers from the collab logger.
+
+    Windows keeps an exclusive handle on open log files, so tests and short-lived CLI
+    commands need an explicit close path when they finish.
+    """
+    collab_logger = logging.getLogger("collab")
+    for handler in list(collab_logger.handlers):
+        if getattr(handler, "baseFilename", None):
+            collab_logger.removeHandler(handler)
+            try:
+                handler.flush()
+            except Exception:
+                pass
+            try:
+                handler.close()
+            except Exception:
+                pass
+
+
+def close_collab_logging() -> None:
+    """Release file-based collab logging handlers for the current process."""
+    _close_collab_file_handlers()
+
+
+def setup_collab_logging(
+    collab_dir: Optional[str] = None, *, level: int = logging.INFO
+) -> logging.Logger:
+    """Configure logging for the collab tooling.
+
+        - collab_dir: runtime root directory. If omitted, the current project's
+            root directory is used, never `src/`.
+    - level: root logger level (defaults to INFO).
+
+    The function is idempotent: calling it multiple times will not attach
+    duplicate handlers.
+    Returns the root logger instance.
+    """
+    # Production logs remain in logs/. Test-mode logs are written to the
+    # isolated state dir so test daemons never lock files in the repo itself.
+    log_dir = _resolve_log_dir(collab_dir)
+    _ensure_dir(log_dir)
+
+    root = logging.getLogger()
+    root.setLevel(level)
+
+    # Simple console handler: keep when not present on the root logger
+    console_present = any(type(h).__name__ == "StreamHandler" for h in root.handlers)
+    if not console_present:
+        ch = logging.StreamHandler()
+        ch.setLevel(level)
+        ch.setFormatter(logging.Formatter(DEFAULT_FORMAT, DEFAULT_DATEFMT))
+        root.addHandler(ch)
+
+    # Configure a dedicated 'collab' logger for file-based logging. This
+    # prevents unrelated libraries or the application root logger from
+    # polluting the logs/ files. Handlers are attached to the
+    # 'collab' logger (and not to the root logger) so only logs emitted by
+    # 'collab' namespace (e.g. "src.lock_client", "collab.pycharm_watcher")
+    # are written to collab.log / test_collab.log.
+    collab_logger = logging.getLogger("collab")
+    collab_logger.setLevel(level)
+    # Allow records to propagate so test harnesses (caplog) and the root
+    # console handler can observe collab log records. FileHandlers are
+    # attached directly to the collab logger so only collab.* records are
+    # written to logs/; other libraries will not be recorded there.
+    collab_logger.propagate = True
+
+    # Single file handler: `collab.log` will contain both INFO and ERROR records.
+    # In test mode we use a distinct filename to avoid Windows file locks
+    # when the live daemon and tests run concurrently.
+    if os.getenv("COLLAB_TEST_MODE") == "1":
+        collab_name = "test_collab.log"
+    else:
+        collab_name = "collab.log"
+
+    collab_path = os.path.join(log_dir, collab_name)
+    _prune_old_log_files(log_dir, collab_name)
+
+    def _has_filehandler_for(logger_obj: logging.Logger, path: str) -> bool:
+        for h in getattr(logger_obj, "handlers", []):
+            if getattr(h, "baseFilename", None) == os.path.abspath(path):
+                return True
+        return False
+
+    # Remove stale file handlers so switching between test and production mode
+    # does not leave old file handles attached.
+    _stale = []
+    for h in list(collab_logger.handlers):
+        bf = getattr(h, "baseFilename", None)
+        if bf and bf != os.path.abspath(collab_path):
+            _stale.append(h)
+    for h in _stale:
+        collab_logger.removeHandler(h)
+        try:
+            h.close()
+        except Exception:
+            pass
+
+    if not _has_filehandler_for(collab_logger, collab_path):
+        try:
+            fh = RotatingFileHandler(
+                collab_path,
+                maxBytes=DEFAULT_LOG_MAX_BYTES,
+                backupCount=DEFAULT_LOG_BACKUP_COUNT,
+                encoding="utf-8",
+            )
+            # Use the provided root level so the single file captures INFO+ (and ERROR)
+            fh.setLevel(level)
+            fh.setFormatter(logging.Formatter(DEFAULT_FORMAT, DEFAULT_DATEFMT))
+            collab_logger.addHandler(fh)
+        except Exception:
+            # Best-effort: continue with console-only logging if file can't be opened
+            pass
+
+    # Return the root logger for convenience (callers typically ignore return)
+    return root
+
+
+atexit.register(close_collab_logging)

src/main.py

@@ -0,0 +1,436 @@
+"""CLI orchestration layer for the collab package.
+
+Separates command-line interface concerns from the core LockClient library, enabling
+plugin/extension architecture for library consumers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+import traceback as _tb
+from argparse import ArgumentParser
+from contextlib import nullcontext
+
+logger = logging.getLogger("collab.lock_client")
+
+
+def _is_truthy_env(name: str, default: bool) -> bool:
+    """Return normalized boolean value for an env var."""
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _should_auto_start_watcher() -> bool:
+    """Decide whether CLI should auto-bootstrap the watcher daemon."""
+    # Keep pytest deterministic: command tests should not spawn background
+    # processes unless a test explicitly opts into that behavior.
+    if os.getenv("PYTEST_CURRENT_TEST"):
+        return False
+    return _is_truthy_env("COLLAB_AUTO_START_WATCHER", default=True)
+
+
+def _ensure_watcher_running(client: object, command: str) -> bool:
+    """Best-effort watcher bootstrap for user-facing commands.
+
+    Returns True when this call started the daemon.
+    """
+    if command not in {"active", "status"}:
+        return False
+    if not _should_auto_start_watcher():
+        return False
+
+    try:
+        if bool(getattr(client, "daemon_status")()):
+            return False
+    except Exception as exc:
+        logger.debug("Failed to determine daemon status before auto-start: %s", exc)
+
+    try:
+        logger.info("Auto-starting watcher daemon for command: %s", command)
+        getattr(client, "daemon_start")()
+        return True
+    except Exception as exc:
+        logger.warning("Watcher auto-start failed for '%s': %s", command, exc)
+        return False
+
+
+def _run_cli() -> None:
+    """CLI entry point for the lock client."""
+    # Force UTF-8 on Windows so Unicode symbols (✓, ❌, 🔒) render correctly.
+    # Mirrors the proven pattern from validate_code.py, format_code.py, run.py.
+    # errors="replace" ensures graceful fallback if the terminal truly cannot
+    # handle a character (e.g. bare cmd.exe with cp437).
+    for stream in (sys.stdout, sys.stderr):
+        reconfig = getattr(stream, "reconfigure", None)
+        if callable(reconfig):
+            try:
+                reconfig(encoding="utf-8", errors="replace")
+            except Exception as exc:
+                logger.debug("Failed to reconfigure stream encoding: %s", exc)
+
+    # Lazy imports to avoid circular dependency with lock_client
+    from .lock_client import _COLLAB_ROOT, LockClient, _quiet_console_loggers
+
+    # Wire up file-based logging early so all CLI output is captured.
+    from .logging_config import setup_collab_logging
+
+    setup_collab_logging(collab_dir=_COLLAB_ROOT)
+
+    parser = ArgumentParser(description="Collaborative File Lock Manager (Supabase)")
+    sub = parser.add_subparsers(dest="command")
+
+    # acquire
+    acq = sub.add_parser("acquire", help="Acquire a lock on a file")
+    acq.add_argument("file_path")
+    acq.add_argument("--reason", help="Reason for the lock")
+
+    # release
+    rel = sub.add_parser("release", help="Release a lock on a file")
+    rel.add_argument("file_path")
+
+    # active
+    sub.add_parser("active", help="List all active locks")
+
+    # status
+    st = sub.add_parser("status", help="Check lock status of a file")
+    st.add_argument("file_path")
+
+    # release-all
+    sub.add_parser("release-all", help="Release all locks held by you")
+
+    # force-release
+    fr = sub.add_parser(
+        "force-release",
+        help="Force release a lock (own locks only; admin can release any)",
+    )
+    fr.add_argument("file_path")
+    # force-release-all
+    sub.add_parser("force-release-all", help="Force release all locks (admin only)")
+
+    # acquire-batch
+    ab = sub.add_parser("acquire-batch", help="Acquire locks on multiple files")
+    ab.add_argument("file_paths", nargs="+")
+    ab.add_argument("--reason")
+
+    # release-batch
+    rb = sub.add_parser("release-batch", help="Release locks on multiple files")
+    rb.add_argument("file_paths", nargs="+")
+
+    # daemon-start
+    ds = sub.add_parser("daemon-start", help="Start the watcher daemon")
+    ds.add_argument("--interval", type=int, default=5, help="Poll interval (seconds)")
+    ds.add_argument(
+        "--timeout",
+        type=int,
+        default=0,
+        help="Idle timeout in minutes (0 = disabled)",
+    )
+    ds.add_argument("--open-dashboard", action="store_true")
+
+    # daemon-stop
+    sub.add_parser("daemon-stop", help="Stop the watcher daemon")
+
+    # daemon-status
+    sub.add_parser("daemon-status", help="Check watcher daemon status")
+
+    # cleanup - kill orphaned processes
+    sub.add_parser(
+        "cleanup", help="Kill all orphaned lock_client processes (preserves locks)"
+    )
+
+    # dashboard
+    sub.add_parser("dashboard", help="Open the collaborative dashboard")
+
+    # reconcile
+    sub.add_parser("reconcile", help="Sync local git status with Supabase")
+
+    # history
+    hp = sub.add_parser("history", help="Show lock history")
+    hp.add_argument("file_path", nargs="?")
+    hp.add_argument("--limit", type=int, default=20)
+    hp.add_argument(
+        "--json", action="store_true", dest="json_output", help="Output as raw JSON"
+    )
+
+    # history-prune
+    hpr = sub.add_parser("history-prune", help="Delete lock history older than N days")
+    hpr.add_argument("--days", type=int, default=30, help="Retention window in days")
+
+    # watch (internal, called by daemon-start)
+    wp = sub.add_parser("watch", help="Run watcher in foreground")
+    wp.add_argument("--interval", type=int, default=5)
+    wp.add_argument("--timeout", type=int, default=0)
+    wp.add_argument("--open-dashboard", action="store_true")
+    wp.add_argument(
+        "--daemon",
+        action="store_true",
+        help="Daemon mode: skip parent-PID liveness check",
+    )
+    wp.add_argument(
+        "--parent-pid", type=int, help="Tie watcher lifecycle to this parent PID"
+    )
+    wp.add_argument(
+        "--parent-name", type=str, help="Name of the parent process for better logging"
+    )
+    wp.add_argument(
+        "--parent-method",
+        type=str,
+        help=(
+            "Detection method used to infer parent PID (vscode_pid|"
+            "process_tree|simple_walk|pycharm_hosted|node_parent|"
+            "immediate_parent)"
+        ),
+    )
+    wp.add_argument(
+        "--heartbeat-file",
+        type=str,
+        help=(
+            "Optional path to a heartbeat file. If missing or stale, "
+            "watcher shuts down."
+        ),
+    )
+    wp.add_argument(
+        "--heartbeat-grace-seconds",
+        type=int,
+        default=10,
+        help="Heartbeat staleness threshold in seconds before shutdown.",
+    )
+    wp.add_argument(
+        "--pid-file",
+        type=str,
+        help="PID file path namespace for this watcher instance.",
+    )
+
+    args = parser.parse_args()
+    local_only = args.command in ("daemon-status", "daemon-stop")
+    client = LockClient(local_only=local_only)
+
+    # Keep CLI output clean by silencing noisy dependency logs (httpx, urllib3,
+    # postgrest, supabase) for user-facing commands that can hit network APIs.
+    quiet_commands = {
+        "acquire",
+        "release",
+        "active",
+        "status",
+        "release-all",
+        "force-release",
+        "force-release-all",
+        "acquire-batch",
+        "release-batch",
+        "daemon-stop",
+        "reconcile",
+        "history",
+        "history-prune",
+    }
+    quiet_ctx = (
+        _quiet_console_loggers() if args.command in quiet_commands else nullcontext()
+    )
+
+    with quiet_ctx:
+        if args.command == "acquire":
+            ok, msg = client.acquire(args.file_path, reason=args.reason)
+            if ok:
+                print(f"✓ Locked {args.file_path} (ID: {msg})")
+            else:
+                print(f"✗ Failed to lock {args.file_path}: {msg}")
+            sys.exit(0 if ok else 1)
+
+        elif args.command == "release":
+            ok, msg = client.release(args.file_path)
+            print(f"{'✓' if ok else '✗'} {msg}")
+
+        elif args.command == "active":
+            started_watcher = _ensure_watcher_running(client, "active")
+            if started_watcher:
+                try:
+                    # Prime lock state immediately so `collab active` reflects
+                    # current git changes right after watcher bootstrap.
+                    client._reconcile()
+                except Exception as exc:
+                    logger.debug("Auto-start reconcile failed: %s", exc)
+            locks = client.active()
+            if not locks:
+                print("No active locks.")
+            else:
+                for lk in locks:
+                    print(
+                        f"  {lk.get('file_path')} — @{lk.get('developer_id')} "
+                        f"(branch: {lk.get('branch_name', 'N/A')}, "
+                        f"reason: {lk.get('reason', 'N/A')})"
+                    )
+
+        elif args.command == "status":
+            _ensure_watcher_running(client, "status")
+            info = client.get_lock_status(args.file_path)
+            if info.get("is_locked"):
+                locked_by = info.get("locked_by")
+                acquired_at = info.get("acquired_at")
+                print(f"🔒 Locked by @{locked_by} since {acquired_at}")
+            else:
+                print("🔓 File is unlocked.")
+
+        elif args.command == "release-all":
+            count = client.release_all()
+            print(f"Released {count} lock(s).")
+
+        elif args.command == "force-release":
+            ok, msg = client.force_release(args.file_path)
+            print(f"{'✓' if ok else '✗'} {msg}")
+
+        elif args.command == "force-release-all":
+            if not client.is_admin:
+                print("✗ Permission denied: admin required to force-release all locks.")
+                sys.exit(1)
+            count = client.force_release_all()
+
+            # Minimal, user-facing output
+            print(f"✓ Force-released {count} lock(s).")
+            sys.exit(0)
+
+        elif args.command == "acquire-batch":
+            ok, failed, msg = client.acquire_multiple(
+                args.file_paths, reason=getattr(args, "reason", None)
+            )
+            if ok:
+                print(f"✓ Locked {len(args.file_paths)} file(s).")
+            else:
+                print(f"✗ {msg}. Failed: {failed}")
+                sys.exit(1)
+
+        elif args.command == "release-batch":
+            ok, count, msg = client.release_multiple(args.file_paths)
+            print(f"Released {count} lock(s).")
+
+        elif args.command == "daemon-start":
+            open_flag = getattr(args, "open_dashboard", False)
+            auto_env = os.getenv("AUTO_OPEN_DASHBOARD", "0").lower() in (
+                "1",
+                "true",
+                "yes",
+            )
+            client.daemon_start(
+                interval=getattr(args, "interval", 5),
+                timeout_mins=getattr(args, "timeout", 0),
+                open_dashboard=(open_flag or auto_env),
+            )
+
+        elif args.command == "daemon-stop":
+            # Suppress collab.* info logs from echoing to the terminal while
+            # performing the stop action (they will still be written to
+            # logs/collab.log).
+            client.daemon_stop()
+
+        elif args.command == "daemon-status":
+            running = client.daemon_status()
+            sys.exit(0 if running else 1)
+
+        elif args.command == "cleanup":
+            client.cleanup_orphaned_processes()
+
+        elif args.command == "dashboard":
+            client.dashboard()
+            print("Dashboard local server running. Press Ctrl+C to stop.")
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                pass
+
+        elif args.command == "reconcile":
+            client._reconcile()
+
+        elif args.command == "history":
+            fp = getattr(args, "file_path", None)
+            rows = client.history(fp, limit=getattr(args, "limit", 20))
+            if getattr(args, "json_output", False):
+                print(json.dumps(rows, indent=2))
+            elif not rows:
+                if fp:
+                    print(f"No history found for '{fp}'.")
+                    print("  Tip: run 'collab history' (no file) to see all.")
+                else:
+                    print("No lock history found.")
+            else:
+                # Check if results came from fallback (partial match)
+                if fp and rows and rows[0].get("file_path") != fp:
+                    actual = rows[0].get("file_path", "")
+                    print(
+                        f"  (No exact match for '{fp}' — "
+                        f"showing partial matches for '{actual.rsplit('/', 1)[-1]}')\n"
+                    )
+                for row in rows:
+                    acquired = row.get("acquired_at", "?")[:19].replace("T", " ")
+                    released = row.get("released_at", "?")[:19].replace("T", " ")
+                    dev = row.get("developer_id", "?")
+                    fpath = row.get("file_path", "?")
+                    branch = row.get("branch_name", "")
+                    outcome = row.get("outcome", "?")
+                    print(
+                        f"  {fpath}  @{dev}  "
+                        f"[{acquired} → {released}]  "
+                        f"branch:{branch}  {outcome}"
+                    )
+
+        elif args.command == "history-prune":
+            days = int(getattr(args, "days", 30))
+            ok, deleted, msg = client.prune_history(retention_days=days)
+            if ok:
+                print(
+                    f"✓ Pruned {deleted} lock history row(s) "
+                    f"older than {days} day(s)."
+                )
+            else:
+                print(f"✗ Failed to prune lock history: {msg}")
+                sys.exit(1)
+
+        elif args.command == "watch":
+            # Ensure watcher child process uses the explicit PID namespace passed by
+            # daemon-start. This prevents cross-instance status/stop interference.
+            if getattr(args, "pid_file", None):
+                from . import lock_client as _lc
+
+                _lc.PID_FILE = str(getattr(args, "pid_file"))
+            client.watch(
+                interval=getattr(args, "interval", 5),
+                timeout_mins=getattr(args, "timeout", 0),
+                open_dashboard=getattr(args, "open_dashboard", False),
+                daemon_mode=getattr(args, "daemon", False),
+                parent_pid=getattr(args, "parent_pid", None),
+                parent_name=getattr(args, "parent_name", None),
+                parent_method=getattr(args, "parent_method", None),
+                heartbeat_file=getattr(args, "heartbeat_file", None),
+                heartbeat_grace_seconds=getattr(args, "heartbeat_grace_seconds", 10),
+            )
+
+        else:
+            parser.print_help()
+
+
+def main() -> None:
+    """Entry point for the collab CLI.
+
+    Orchestrates exception handling and error logging for the command-line interface.
+    Can be called from run.py, collab CLI, or package consumers that want to invoke the
+    CLI programmatically.
+    """
+    try:
+        _run_cli()
+    except Exception as exc:
+        tb_str = _tb.format_exc()
+        # Log to the standard logs/ directory via the structured logger.
+        logger.error("Unhandled exception: %s\n%s", exc, tb_str)
+        print(
+            "FATAL: lock_client crashed — see logs/collab.log",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()