procclean 1.2.0__py3-none-any.whl

procclean/cli/parser.py

@@ -0,0 +1,272 @@
+"""CLI argument parser."""
+
+import argparse
+from importlib.metadata import version
+
+from procclean.formatters import get_available_columns
+
+from .commands import cmd_groups, cmd_kill, cmd_list, cmd_memory
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create CLI argument parser.
+
+    Returns:
+        argparse.ArgumentParser: Configured argument parser for the CLI.
+    """
+    parser = argparse.ArgumentParser(
+        prog="procclean",
+        description="Process cleanup tool with TUI and CLI interfaces.",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('procclean')}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # List command
+    list_parser = subparsers.add_parser("list", aliases=["ls"], help="List processes")
+    list_parser.add_argument(
+        "-f",
+        "--format",
+        choices=["table", "json", "csv", "md"],
+        default="table",
+        help="Output format (default: table)",
+    )
+    list_parser.add_argument(
+        "-s",
+        "--sort",
+        choices=["memory", "mem", "cpu", "pid", "name", "cwd"],
+        default="memory",
+        help="Sort by field (default: memory)",
+    )
+    list_parser.add_argument(
+        "-a",
+        "--ascending",
+        action="store_true",
+        help="Sort ascending instead of descending",
+    )
+    list_parser.add_argument(
+        "-F",
+        "--filter",
+        choices=["killable", "orphans", "high-memory"],
+        help="Filter preset: killable (orphans, not tmux, not system), "
+        "orphans, high-memory",
+    )
+    list_parser.add_argument(
+        "-k",
+        "--killable",
+        action="store_true",
+        help="Shorthand for --filter killable",
+    )
+    list_parser.add_argument(
+        "-o",
+        "--orphans",
+        action="store_true",
+        help="Shorthand for --filter orphans",
+    )
+    list_parser.add_argument(
+        "-m",
+        "--high-memory",
+        action="store_true",
+        help="Shorthand for --filter high-memory",
+    )
+    list_parser.add_argument(
+        "--high-memory-threshold",
+        type=float,
+        default=500.0,
+        metavar="MB",
+        help="Threshold for high memory filter (default: 500 MB)",
+    )
+    list_parser.add_argument(
+        "--min-memory",
+        type=float,
+        default=5.0,
+        metavar="MB",
+        help="Minimum memory to include (default: 5 MB)",
+    )
+    list_parser.add_argument(
+        "-n",
+        "--limit",
+        type=int,
+        metavar="N",
+        help="Limit output to N processes",
+    )
+    list_parser.add_argument(
+        "-c",
+        "--columns",
+        type=str,
+        metavar="COLS",
+        help=f"Comma-separated columns ({','.join(get_available_columns())})",
+    )
+    list_parser.add_argument(
+        "--cwd",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="PATH",
+        help="Filter by cwd (no value = current dir, or specify path/glob)",
+    )
+    list_parser.set_defaults(func=cmd_list)
+
+    # Groups command
+    groups_parser = subparsers.add_parser(
+        "groups", aliases=["g"], help="Show process groups"
+    )
+    groups_parser.add_argument(
+        "-f",
+        "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Output format (default: table)",
+    )
+    groups_parser.add_argument(
+        "--min-memory",
+        type=float,
+        default=5.0,
+        metavar="MB",
+        help="Minimum memory to include (default: 5 MB)",
+    )
+    groups_parser.set_defaults(func=cmd_groups)
+
+    # Kill command
+    kill_parser = subparsers.add_parser("kill", help="Kill process(es)")
+    kill_parser.add_argument(
+        "pids",
+        type=int,
+        nargs="*",
+        metavar="PID",
+        help="Process ID(s) to kill (or use filters)",
+    )
+    kill_parser.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Force kill (SIGKILL instead of SIGTERM)",
+    )
+    kill_parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+    kill_parser.add_argument(
+        "--cwd",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="PATH",
+        help="Kill processes in cwd (no value = current dir, or specify path/glob)",
+    )
+    kill_parser.add_argument(
+        "-F",
+        "--filter",
+        choices=["killable", "orphans", "high-memory"],
+        help="Filter preset to select processes",
+    )
+    kill_parser.add_argument(
+        "-k",
+        "--killable",
+        action="store_true",
+        help="Shorthand for --filter killable",
+    )
+    kill_parser.add_argument(
+        "-o",
+        "--orphans",
+        action="store_true",
+        help="Shorthand for --filter orphans",
+    )
+    kill_parser.add_argument(
+        "-m",
+        "--high-memory",
+        action="store_true",
+        help="Shorthand for --filter high-memory",
+    )
+    kill_parser.add_argument(
+        "--min-memory",
+        type=float,
+        default=5.0,
+        metavar="MB",
+        help="Minimum memory for filter (default: 5 MB)",
+    )
+    kill_parser.add_argument(
+        "--high-memory-threshold",
+        type=float,
+        default=500.0,
+        metavar="MB",
+        help="Threshold for high memory filter (default: 500 MB)",
+    )
+    kill_parser.add_argument(
+        "--preview",
+        "--dry-run",
+        "--dry",
+        action="store_true",
+        dest="preview",
+        help="Show what would be killed without killing",
+    )
+    kill_parser.add_argument(
+        "-O",
+        "--out-format",
+        choices=["table", "json", "csv", "md"],
+        default="table",
+        dest="out_format",
+        help="Output format for preview (default: table)",
+    )
+    kill_parser.add_argument(
+        "-s",
+        "--sort",
+        choices=["memory", "mem", "cpu", "pid", "name", "cwd"],
+        default=None,
+        help="Sort by field for preview",
+    )
+    kill_parser.add_argument(
+        "-n",
+        "--limit",
+        type=int,
+        metavar="N",
+        help="Limit preview output to N processes",
+    )
+    kill_parser.add_argument(
+        "-c",
+        "--columns",
+        type=str,
+        metavar="COLS",
+        help=f"Comma-separated columns for preview "
+        f"({','.join(get_available_columns())})",
+    )
+    kill_parser.set_defaults(func=cmd_kill)
+
+    # Memory command
+    memory_parser = subparsers.add_parser(
+        "memory", aliases=["mem"], help="Show memory summary"
+    )
+    memory_parser.add_argument(
+        "-f",
+        "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Output format (default: table)",
+    )
+    memory_parser.set_defaults(func=cmd_memory)
+
+    return parser
+
+
+def run_cli(args: list[str] | None = None) -> int:
+    """Run CLI with given args (or sys.argv if None).
+
+    Returns:
+        int: Exit status code. Returns ``-1`` when no subcommand is provided to
+        signal that the TUI should run.
+    """
+    parser = create_parser()
+    parsed = parser.parse_args(args)
+
+    if parsed.command is None:
+        # No subcommand - return None to signal TUI should run
+        return -1
+
+    return parsed.func(parsed)

procclean/core/__init__.py

@@ -0,0 +1,47 @@
+"""Core process analysis functionality."""
+
+from .actions import kill_process, kill_processes
+from .constants import (
+    CONFIRM_PREVIEW_LIMIT,
+    CRITICAL_SERVICES,
+    CWD_MAX_WIDTH,
+    CWD_TRUNCATE_WIDTH,
+    HIGH_MEMORY_THRESHOLD_MB,
+    PREVIEW_LIMIT,
+    SYSTEM_EXE_PATHS,
+)
+from .filters import (
+    filter_by_cwd,
+    filter_high_memory,
+    filter_killable,
+    filter_orphans,
+    is_system_service,
+    sort_processes,
+)
+from .memory import get_memory_summary
+from .models import ProcessInfo
+from .process import find_similar_processes, get_cwd, get_process_list, get_tmux_env
+
+__all__ = [
+    "CONFIRM_PREVIEW_LIMIT",
+    "CRITICAL_SERVICES",
+    "CWD_MAX_WIDTH",
+    "CWD_TRUNCATE_WIDTH",
+    "HIGH_MEMORY_THRESHOLD_MB",
+    "PREVIEW_LIMIT",
+    "SYSTEM_EXE_PATHS",
+    "ProcessInfo",
+    "filter_by_cwd",
+    "filter_high_memory",
+    "filter_killable",
+    "filter_orphans",
+    "find_similar_processes",
+    "get_cwd",
+    "get_memory_summary",
+    "get_process_list",
+    "get_tmux_env",
+    "is_system_service",
+    "kill_process",
+    "kill_processes",
+    "sort_processes",
+]

procclean/core/actions.py

@@ -0,0 +1,46 @@
+"""Process kill actions."""
+
+import psutil
+
+
+def kill_process(pid: int, force: bool = False) -> tuple[bool, str]:
+    """Kill a process by PID.
+
+    Args:
+        pid: Process ID to kill.
+        force: If True, force kill the process; otherwise, terminate gracefully.
+
+    Returns:
+        A tuple of (success, message) indicating whether the operation succeeded and
+        providing a human-readable message.
+    """
+    try:
+        proc = psutil.Process(pid)
+        if force:
+            proc.kill()
+        else:
+            proc.terminate()
+        return True, f"Process {pid} terminated"
+    except psutil.NoSuchProcess:
+        return False, f"Process {pid} not found"
+    except psutil.AccessDenied:
+        return False, f"Access denied for process {pid}"
+    except OSError as e:
+        return False, f"Error: {e}"
+
+
+def kill_processes(pids: list[int], force: bool = False) -> list[tuple[int, bool, str]]:
+    """Kill multiple processes.
+
+    Args:
+        pids: Process IDs to kill.
+        force: If True, force kill the processes; otherwise, terminate gracefully.
+
+    Returns:
+        A list of tuples (pid, success, message) for each PID attempted.
+    """
+    results: list[tuple[int, bool, str]] = []
+    for pid in pids:
+        success, msg = kill_process(pid, force)
+        results.append((pid, success, msg))
+    return results

procclean/core/constants.py

@@ -0,0 +1,48 @@
+"""Constants for process analysis."""
+
+# Display constants
+PREVIEW_LIMIT = 5  # Number of processes to show in previews
+CONFIRM_PREVIEW_LIMIT = 10  # Number of processes to show in confirm dialogs
+CWD_MAX_WIDTH = 35  # Max width for cwd column display
+CWD_TRUNCATE_WIDTH = 32  # Width to keep when truncating cwd
+
+# Memory thresholds
+HIGH_MEMORY_THRESHOLD_MB = 500  # Default threshold for high memory filter
+
+# System library paths - executables here are system services
+SYSTEM_EXE_PATHS = ("/usr/lib", "/usr/libexec", "/lib")
+
+# Critical services in /usr/bin that should never be killed
+# (session managers, audio, shells, display, auth)
+CRITICAL_SERVICES = {
+    # Display/session
+    "gnome-shell",
+    "kwin",
+    "plasmashell",
+    "mutter",
+    # Audio
+    "pipewire",
+    "pipewire-pulse",
+    "wireplumber",
+    "pulseaudio",
+    # Remote sessions
+    "tmux: server",
+    "tmux",
+    "mosh-server",
+    # Shells
+    "zsh",
+    "-zsh",
+    "bash",
+    "-bash",
+    "ssh",
+    "sshd",
+    # System
+    "systemd",
+    "init",
+    "dbus-daemon",
+    "dbus-broker",
+    # Desktop services
+    "ibus-daemon",
+    "gjs",
+    "gnome-keyring-daemon",
+}

procclean/core/filters.py

@@ -0,0 +1,121 @@
+"""Process filtering and sorting utilities."""
+
+import fnmatch
+
+import psutil
+
+from .constants import CRITICAL_SERVICES, SYSTEM_EXE_PATHS
+from .models import ProcessInfo
+
+
+def is_system_service(proc: ProcessInfo) -> bool:
+    """Check if process is a system service that shouldn't be killed.
+
+    Uses two heuristics:
+    1. Exe path in system directories (/usr/lib, /usr/libexec)
+    2. Name matches critical services list (shells, audio, display)
+
+    Returns:
+        True if the process looks like a system/critical service, otherwise False.
+    """
+    # Check exe path - most system services live in /usr/lib
+    try:
+        exe = psutil.Process(proc.pid).exe() or ""
+        if exe.startswith(SYSTEM_EXE_PATHS):
+            return True
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        pass
+
+    # Check critical services by name
+    return proc.name.lower() in {s.lower() for s in CRITICAL_SERVICES}
+
+
+def filter_orphans(procs: list[ProcessInfo]) -> list[ProcessInfo]:
+    """Filter to only orphaned processes.
+
+    Args:
+        procs: List of processes to filter.
+
+    Returns:
+        Processes that are marked as orphaned.
+    """
+    return [p for p in procs if p.is_orphan]
+
+
+def filter_killable(procs: list[ProcessInfo]) -> list[ProcessInfo]:
+    """Filter to orphaned processes that are safe to kill.
+
+    Returns:
+        Processes that are:
+        - Orphaned (parent is init/systemd)
+        - Not running in tmux
+        - Not a system service (GNOME, pipewire, etc.)
+    """
+    return [p for p in procs if p.is_orphan_candidate and not is_system_service(p)]
+
+
+def filter_high_memory(
+    procs: list[ProcessInfo], threshold_mb: float = 500.0
+) -> list[ProcessInfo]:
+    """Filter to processes using more than threshold memory.
+
+    Args:
+        procs: List of processes to filter.
+        threshold_mb: Memory threshold in MB.
+
+    Returns:
+        Processes whose RSS memory usage is greater than threshold_mb.
+    """
+    return [p for p in procs if p.rss_mb > threshold_mb]
+
+
+def filter_by_cwd(procs: list[ProcessInfo], cwd_path: str) -> list[ProcessInfo]:
+    """Filter processes by current working directory.
+
+    Args:
+        procs: List of processes to filter
+        cwd_path: Path to match. If contains '*', uses glob matching.
+                  Otherwise, uses prefix matching.
+
+    Returns:
+        Processes whose cwd starts with cwd_path (or matches glob pattern)
+    """
+    if "*" in cwd_path or "?" in cwd_path:
+        # Glob matching
+        return [p for p in procs if p.cwd and fnmatch.fnmatch(p.cwd, cwd_path)]
+    # Prefix matching (normalized)
+    cwd_path = cwd_path.rstrip("/")
+    return [
+        p
+        for p in procs
+        if p.cwd
+        and p.cwd != "?"
+        and (p.cwd == cwd_path or p.cwd.startswith(cwd_path + "/"))
+    ]
+
+
+def sort_processes(
+    procs: list[ProcessInfo],
+    sort_by: str = "memory",
+    reverse: bool = True,
+) -> list[ProcessInfo]:
+    """Sort processes by given key.
+
+    Args:
+        procs: List of processes to sort
+        sort_by: One of 'memory', 'cpu', 'pid', 'name', 'cwd'
+        reverse: If True, sort descending (default for numeric)
+
+    Returns:
+        A new list of processes sorted by the requested key.
+    """
+    sort_keys = {
+        "memory": lambda p: p.rss_mb,
+        "mem": lambda p: p.rss_mb,
+        "cpu": lambda p: p.cpu_percent,
+        "pid": lambda p: p.pid,
+        "name": lambda p: p.name.lower(),
+        "cwd": lambda p: p.cwd.lower() if p.cwd else "",
+    }
+    key_func = sort_keys.get(sort_by, sort_keys["memory"])
+    return sorted(procs, key=key_func, reverse=reverse)

procclean/core/memory.py

@@ -0,0 +1,22 @@
+"""Memory summary utilities."""
+
+import psutil
+
+
+def get_memory_summary() -> dict:
+    """Get system memory summary.
+
+    Returns:
+        dict: A dictionary containing total, used, and available memory in GB,
+        memory usage percentage, and swap usage/total in GB.
+    """
+    mem = psutil.virtual_memory()
+    swap = psutil.swap_memory()
+    return {
+        "total_gb": mem.total / 1024**3,
+        "used_gb": mem.used / 1024**3,
+        "free_gb": mem.available / 1024**3,
+        "percent": mem.percent,
+        "swap_used_gb": swap.used / 1024**3,
+        "swap_total_gb": swap.total / 1024**3,
+    }

procclean/core/models.py

@@ -0,0 +1,27 @@
+"""Process data models."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ProcessInfo:
+    """Process information data class."""
+
+    pid: int
+    name: str
+    cmdline: str
+    cwd: str
+    ppid: int
+    parent_name: str
+    rss_mb: float
+    cpu_percent: float
+    username: str
+    create_time: float
+    is_orphan: bool
+    in_tmux: bool
+    status: str
+
+    @property
+    def is_orphan_candidate(self) -> bool:
+        """Check if process is orphaned (PPID=1 or user systemd)."""
+        return self.is_orphan and not self.in_tmux