procclean 1.2.0__py3-none-any.whl

procclean/__init__.py

@@ -0,0 +1,11 @@
+"""Process cleanup TUI application."""
+
+from importlib.metadata import version
+
+__version__ = version("procclean")
+
+# Re-export main entry point and core types
+from procclean.__main__ import main
+from procclean.core import ProcessInfo
+
+__all__ = ["ProcessInfo", "__version__", "main"]

procclean/__main__.py

@@ -0,0 +1,22 @@
+"""Entry point for procclean - runs as python -m procclean or via console script."""
+
+from .cli import run_cli
+from .tui import ProcessCleanerApp
+
+
+def main() -> None:
+    """Dispatch to CLI or run TUI.
+
+    Raises:
+        SystemExit: When CLI command returns non-zero exit code.
+    """
+    result = run_cli()
+    if result == -1:
+        # No subcommand - run TUI
+        ProcessCleanerApp().run()
+    else:
+        raise SystemExit(result)
+
+
+if __name__ == "__main__":
+    main()

procclean/cli/__init__.py

@@ -0,0 +1,27 @@
+"""CLI interface for procclean."""
+
+# Internal helpers - exported for testing
+from .commands import (
+    _confirm_kill,
+    _do_preview,
+    _get_kill_targets,
+    cmd_groups,
+    cmd_kill,
+    cmd_list,
+    cmd_memory,
+    get_filtered_processes,
+)
+from .parser import create_parser, run_cli
+
+__all__ = [
+    "_confirm_kill",
+    "_do_preview",
+    "_get_kill_targets",
+    "cmd_groups",
+    "cmd_kill",
+    "cmd_list",
+    "cmd_memory",
+    "create_parser",
+    "get_filtered_processes",
+    "run_cli",
+]

procclean/cli/commands.py

@@ -0,0 +1,213 @@
+"""CLI command handlers."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich import print  # pylint: disable=redefined-builtin
+
+from procclean.core import (
+    PREVIEW_LIMIT,
+    filter_by_cwd,
+    filter_high_memory,
+    filter_killable,
+    filter_orphans,
+    find_similar_processes,
+    get_memory_summary,
+    get_process_list,
+    kill_processes,
+    sort_processes,
+)
+from procclean.formatters import format_output
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List processes command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    procs = get_filtered_processes(args)
+
+    # Apply sorting
+    reverse = not args.ascending
+    procs = sort_processes(procs, sort_by=args.sort, reverse=reverse)
+
+    # Limit output
+    if args.limit:
+        procs = procs[: args.limit]
+
+    # Parse columns
+    columns = args.columns.split(",") if args.columns else None
+
+    print(format_output(procs, args.format, columns=columns))
+    return 0
+
+
+def cmd_groups(args: argparse.Namespace) -> int:
+    """Show grouped processes command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    procs = get_process_list(min_memory_mb=args.min_memory)
+    groups = find_similar_processes(procs)
+
+    if not groups:
+        print("No process groups found.")
+        return 0
+
+    if args.format == "json":
+        data = {
+            cmd: [
+                {"pid": p.pid, "name": p.name, "rss_mb": round(p.rss_mb, 2)}
+                for p in group_procs
+            ]
+            for cmd, group_procs in groups.items()
+        }
+        print(json.dumps(data, indent=2))
+    else:
+        for cmd, group_procs in sorted(
+            groups.items(), key=lambda x: sum(p.rss_mb for p in x[1]), reverse=True
+        ):
+            total_mb = sum(p.rss_mb for p in group_procs)
+            print(f"\n{cmd} ({len(group_procs)} processes, {total_mb:.1f} MB total)")
+            for p in sorted(group_procs, key=lambda x: x.rss_mb, reverse=True):
+                print(f"  PID {p.pid}: {p.rss_mb:.1f} MB")
+
+    return 0
+
+
+def get_filtered_processes(args: argparse.Namespace) -> list:
+    """Get processes with all filters from args applied.
+
+    Returns:
+        list: Filtered list of processes.
+    """
+    procs = get_process_list(min_memory_mb=getattr(args, "min_memory", 5.0))
+
+    # Apply cwd filter
+    if getattr(args, "cwd", None) is not None:
+        cwd_path = args.cwd or str(Path.cwd())
+        procs = filter_by_cwd(procs, cwd_path)
+
+    # Apply preset filters
+    filt = getattr(args, "filter", None)
+    threshold = getattr(args, "high_memory_threshold", 500.0)
+    if filt == "killable" or getattr(args, "killable", False):
+        procs = filter_killable(procs)
+    elif filt == "orphans" or getattr(args, "orphans", False):
+        procs = filter_orphans(procs)
+    elif filt == "high-memory" or getattr(args, "high_memory", False):
+        procs = filter_high_memory(procs, threshold_mb=threshold)
+
+    return procs
+
+
+def _get_kill_targets(args: argparse.Namespace) -> list:
+    """Get target processes for kill command from PIDs or filters.
+
+    Returns:
+        list: Target processes to kill.
+    """
+    if args.pids:
+        all_procs = get_process_list(min_memory_mb=0)
+        pid_set = set(args.pids)
+        procs = [p for p in all_procs if p.pid in pid_set]
+        found_pids = {p.pid for p in procs}
+        for pid in args.pids:
+            if pid not in found_pids:
+                print(f"Warning: PID {pid} not found")
+        return procs
+    return get_filtered_processes(args)
+
+
+def _do_preview(args: argparse.Namespace, procs: list) -> int:
+    """Show preview of what would be killed.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    if hasattr(args, "sort") and args.sort:
+        procs = sort_processes(procs, sort_by=args.sort, reverse=True)
+    if hasattr(args, "limit") and args.limit:
+        procs = procs[: args.limit]
+    columns = args.columns.split(",") if getattr(args, "columns", None) else None
+    fmt = getattr(args, "out_format", "table")
+    print(format_output(procs, fmt, columns=columns))
+    print(f"\n{len(procs)} process(es) would be killed.")
+    return 0
+
+
+def _confirm_kill(args: argparse.Namespace, procs: list) -> bool:
+    """Prompt for kill confirmation.
+
+    Args:
+        args: Parsed CLI arguments.
+        procs: Processes that would be killed.
+
+    Returns:
+        True if the kill action is confirmed (or confirmation is skipped), otherwise
+        False.
+    """
+    if args.yes or not sys.stdin.isatty():
+        return True
+    action = "FORCE KILL" if args.force else "terminate"
+    print(f"About to {action} {len(procs)} process(es):")
+    for p in procs[:PREVIEW_LIMIT]:
+        print(f"  {p.pid}: {p.name} ({p.rss_mb:.1f} MB)")
+    if len(procs) > PREVIEW_LIMIT:
+        print(f"  ... and {len(procs) - PREVIEW_LIMIT} more")
+    try:
+        response = input("Continue? [y/N] ")
+        return response.lower() in {"y", "yes"}
+    except EOFError:
+        return True  # Non-interactive
+
+
+def cmd_kill(args: argparse.Namespace) -> int:
+    """Kill processes command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    procs = _get_kill_targets(args)
+    if not procs:
+        print("No processes match the filters.")
+        return 0
+
+    if getattr(args, "preview", False):
+        return _do_preview(args, procs)
+
+    if not _confirm_kill(args, procs):
+        print("Aborted.")
+        return 1
+
+    results = kill_processes([p.pid for p in procs], force=args.force)
+    exit_code = 0
+    for _, success, msg in results:
+        status = "OK" if success else "FAILED"
+        print(f"[{status}] {msg}")
+        if not success:
+            exit_code = 1
+    return exit_code
+
+
+def cmd_memory(args: argparse.Namespace) -> int:
+    """Show memory summary command.
+
+    Returns:
+        int: Exit code (0 on success).
+    """
+    mem = get_memory_summary()
+
+    if args.format == "json":
+        print(json.dumps(mem, indent=2))
+    else:
+        print(f"Total:  {mem['total_gb']:.2f} GB")
+        print(f"Used:   {mem['used_gb']:.2f} GB ({mem['percent']:.1f}%)")
+        print(f"Free:   {mem['free_gb']:.2f} GB")
+        print(f"Swap:   {mem['swap_used_gb']:.2f} / {mem['swap_total_gb']:.2f} GB")
+
+    return 0

procclean/cli/docs.py

@@ -0,0 +1,234 @@
+"""CLI documentation generation utilities."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import os
+import re
+from collections import defaultdict
+from pathlib import Path
+
+from markdown_it import MarkdownIt
+from rich.console import Console
+from rich.text import Text
+from rich_argparse import RichHelpFormatter
+
+from .parser import create_parser
+
+DOCS_CLI_PATH = Path(__file__).parent.parent.parent.parent / "docs" / "cli.md"
+HEADER_COMMENT = (
+    "<!-- AUTO-GENERATED - DO NOT EDIT -->\n"
+    "<!-- Run: ./scripts/generate_cli_docs.py -->\n"
+    "<!-- dprint-ignore-file -->\n"
+    "<!-- markdownlint-disable-file -->\n\n"
+)
+
+# Apply custom styles for CLI help output (once at module load)
+_HELP_STYLES = {
+    "prog": "#98f641",
+    "args": "#54ebdd",
+    "groups": "#98f641",
+    "metavar": "#7af0e5",
+    "syntax": "#98f641",
+    "help": "white",
+    "text": "white",
+    "default": "#888888",
+}
+for _key, _value in _HELP_STYLES.items():
+    RichHelpFormatter.styles[f"argparse.{_key}"] = _value
+
+_PRE_STYLE = "font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"
+_CODE_FORMAT = (
+    f'<pre style="{_PRE_STYLE}">\n'
+    '<code style="font-family:inherit" class="nohighlight">{code}</code>\n'
+    "</pre>\n"
+)
+
+
+def _capture_help(parser: argparse.ArgumentParser) -> str:
+    """Capture the help text of an argparse parser as colored HTML.
+
+    Returns:
+        HTML string with colored help output.
+    """
+    # Force colored output even when not in a TTY
+    old_force_color = os.environ.get("FORCE_COLOR")
+    os.environ["FORCE_COLOR"] = "1"
+    try:
+        parser.formatter_class = RichHelpFormatter
+        text = Text.from_ansi(parser.format_help())
+    finally:
+        if old_force_color is None:
+            os.environ.pop("FORCE_COLOR", None)
+        else:
+            os.environ["FORCE_COLOR"] = old_force_color
+
+    # force_terminal=True ensures colored output even when not in a TTY
+    console = Console(file=io.StringIO(), record=True, force_terminal=True)
+    console.print(text, crop=False)
+
+    return console.export_html(code_format=_CODE_FORMAT, inline_styles=True)
+
+
+def _argparser_to_markdown(
+    parser: argparse.ArgumentParser,
+    heading: str = "CLI Reference",
+) -> str:
+    """Convert an argparse parser to markdown documentation with colored output.
+
+    Args:
+        parser: The argparse parser to document.
+        heading: The main heading for the documentation.
+
+    Returns:
+        Markdown string with colored HTML help blocks.
+    """
+    prog = parser.prog
+    main_help = _capture_help(parser).rstrip()
+
+    lines = [
+        f"# {heading}",
+        "",
+        f"Documentation for the `{prog}` script.",
+        "",
+        "```console",
+        f"{prog} --help",
+        "```",
+        "",
+        main_help,
+    ]
+
+    # Find subparsers
+    subparsers_actions = [
+        action
+        for action in parser._actions  # noqa: SLF001
+        if isinstance(action, argparse._SubParsersAction)  # noqa: SLF001
+    ]
+
+    if subparsers_actions:
+        current_subparsers_action = subparsers_actions[0]
+        for sub_cmd_name, sub_cmd_parser in current_subparsers_action.choices.items():
+            sub_cmd_help_text = _capture_help(sub_cmd_parser).rstrip()
+            lines.extend([
+                "",
+                f"## {sub_cmd_name}",
+                "",
+                "```console",
+                f"{prog} {sub_cmd_name} --help",
+                "```",
+                "",
+                sub_cmd_help_text,
+            ])
+
+    return "\n".join(lines)
+
+
+def _extract_h2_sections(
+    markdown: str,
+) -> tuple[list[str], list[tuple[str, int, int]]]:
+    """Extract h2 sections from markdown using AST.
+
+    Uses markdown-it parser to reliably detect headings
+    (won't match ## inside fenced code blocks).
+
+    Returns:
+        Tuple of (lines, sections) where sections is list of (title, start, end).
+    """
+    md = MarkdownIt()
+    tokens = md.parse(markdown)
+    lines = markdown.split("\n")
+
+    h2_starts: list[tuple[str, int]] = []
+    for i, token in enumerate(tokens):
+        if token.type == "heading_open" and token.tag == "h2":
+            title = tokens[i + 1].content
+            start_line = token.map[0]  # type: ignore[index]
+            h2_starts.append((title, start_line))
+
+    h2_sections: list[tuple[str, int, int]] = []
+    for i, (title, start) in enumerate(h2_starts):
+        end = h2_starts[i + 1][1] if i + 1 < len(h2_starts) else len(lines)
+        h2_sections.append((title, start, end))
+
+    return lines, h2_sections
+
+
+def _normalize_content(content: str) -> str:
+    """Normalize content for comparison by removing command-specific parts.
+
+    Returns:
+        Content with command invocations normalized and whitespace stripped.
+    """
+    normalized = re.sub(r"procclean \w+ --help", "procclean CMD --help", content)
+    return normalized.strip()
+
+
+def merge_alias_sections(markdown: str) -> str:
+    """Merge duplicate argparse alias sections in CLI markdown.
+
+    Detects sections with identical help content (modulo command name)
+    and merges their headers, e.g., `## list` + `## ls` -> `## list / ls`.
+
+    Returns:
+        Markdown with merged alias sections.
+    """
+    lines, h2_sections = _extract_h2_sections(markdown)
+    if not h2_sections:
+        return markdown
+
+    # Group by normalized content
+    content_to_titles: dict[str, list[str]] = defaultdict(list)
+    for title, start, end in h2_sections:
+        content = "\n".join(lines[start + 1 : end])
+        normalized = _normalize_content(content)
+        content_to_titles[normalized].append(title)
+
+    # Rebuild with merged headers
+    result = lines[: h2_sections[0][1]][:]
+    seen: set[str] = set()
+
+    for _title, start, end in h2_sections:
+        content = "\n".join(lines[start + 1 : end])
+        normalized = _normalize_content(content)
+
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+
+        aliases = content_to_titles[normalized]
+        header = " / ".join(f"`{a}`" for a in aliases)
+
+        result.append(f"## {header}")
+        result.extend(lines[start + 1 : end])
+
+    return "\n".join(result)
+
+
+def generate_cli_docs() -> str:
+    """Generate merged CLI documentation from argparse parser.
+
+    Returns:
+        Complete CLI reference markdown with header comment.
+    """
+    parser = create_parser()
+    markdown = _argparser_to_markdown(parser, heading="CLI Reference")
+    merged = merge_alias_sections(markdown)
+    return HEADER_COMMENT + merged
+
+
+def write_cli_docs() -> bool:
+    """Generate and write CLI docs to docs/cli.md.
+
+    Returns:
+        True if file was updated, False if unchanged.
+    """
+    new_content = generate_cli_docs()
+
+    if DOCS_CLI_PATH.exists():
+        existing = DOCS_CLI_PATH.read_text()
+        if existing == new_content:
+            return False
+
+    DOCS_CLI_PATH.write_text(new_content)
+    return True