optforge 0.2.0__py3-none-any.whl

optforge/__init__.py

@@ -0,0 +1,17 @@
+"""OptForge: cross-platform developer utilities with a stable, scriptable CLI."""
+
+from __future__ import annotations
+
+from optforge.core.version import get_version
+
+__version__ = get_version()
+
+
+def main() -> None:
+    """Entry point for the ``optforge`` dispatcher."""
+    from optforge.cli import app
+
+    app()
+
+
+__all__ = ["__version__", "main"]

optforge/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m optforge``."""
+
+from optforge import main
+
+if __name__ == "__main__":
+    main()

optforge/cli.py

@@ -0,0 +1,56 @@
+"""The ``optforge`` dispatcher that exposes every tool as a subcommand."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from optforge.core.version import get_version
+from optforge.diskcheck.cli import app as diskcheck_app
+from optforge.envcheck.cli import app as envcheck_app
+from optforge.portcheck.cli import app as portcheck_app
+from optforge.pycacheclean.cli import app as pycacheclean_app
+from optforge.volume.cli import app as volume_app
+
+app = typer.Typer(
+    name="optforge",
+    help="Developer utilities for ports, environment variables, disk usage, Python caches, and volume.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"optforge {get_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    pass
+
+
+app.add_typer(portcheck_app, name="portcheck")
+app.add_typer(envcheck_app, name="envcheck")
+app.add_typer(diskcheck_app, name="diskcheck")
+app.add_typer(pycacheclean_app, name="pycache-clean")
+app.add_typer(pycacheclean_app, name="pycacheClean", hidden=True)
+app.add_typer(volume_app, name="vol")
+
+
+if __name__ == "__main__":
+    app()

optforge/core/__init__.py

@@ -0,0 +1,24 @@
+"""Shared infrastructure used by every OptForge tool."""
+
+from optforge.core.console import ConsoleIO
+from optforge.core.errors import (
+    InvalidInput,
+    NotFound,
+    OperationFailed,
+    OptForgeError,
+    PermissionDenied,
+)
+from optforge.core.formatting import format_bytes, format_percent
+from optforge.core.version import get_version
+
+__all__ = [
+    "ConsoleIO",
+    "InvalidInput",
+    "NotFound",
+    "OperationFailed",
+    "OptForgeError",
+    "PermissionDenied",
+    "format_bytes",
+    "format_percent",
+    "get_version",
+]

optforge/core/cli.py

@@ -0,0 +1,56 @@
+"""Shared CLI plumbing: exit codes and a consistent error boundary."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from types import TracebackType
+from typing import Self
+
+import typer
+
+from optforge.core.console import ConsoleIO
+from optforge.core.errors import OptForgeError, PermissionDenied
+
+
+class ExitCode(IntEnum):
+    """Exit codes shared by every OptForge command.
+
+    ``0`` and ``1`` answer a yes/no question; ``2`` is reserved by Typer for
+    invalid usage; ``3`` means the check could not run.
+    """
+
+    OK = 0
+    NO = 1
+    ERROR = 3
+
+
+class ErrorBoundary:
+    """Convert expected exceptions into a clean message and exit code 3.
+
+    Unexpected exceptions are re-raised untouched so they keep their traceback.
+    """
+
+    def __init__(self, console: ConsoleIO, *, permission_hint: str | None = None) -> None:
+        self._console = console
+        self._permission_hint = permission_hint
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        if exc is None:
+            return False
+        if isinstance(exc, PermissionDenied):
+            self._console.error(str(exc))
+            if self._permission_hint:
+                self._console.hint(self._permission_hint)
+            raise typer.Exit(ExitCode.ERROR) from exc
+        if isinstance(exc, OptForgeError):
+            self._console.error(str(exc))
+            raise typer.Exit(ExitCode.ERROR) from exc
+        return False

optforge/core/console.py

@@ -0,0 +1,83 @@
+"""A thin, markup-safe wrapper around Rich consoles.
+
+Every value that comes from the operating system (process names, environment
+variables, paths) is rendered through :class:`rich.text.Text` so a value such as
+``[red]oops`` can never inject markup into the terminal.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Sequence
+from contextlib import AbstractContextManager
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+
+class ConsoleIO:
+    """Human output on stdout and diagnostics on stderr."""
+
+    def __init__(
+        self,
+        out: Console | None = None,
+        err: Console | None = None,
+        *,
+        force_terminal: bool | None = None,
+    ) -> None:
+        self.out = out or Console(force_terminal=force_terminal)
+        self.err = err or Console(stderr=True, force_terminal=force_terminal)
+
+    def print(self, *values: Any, **kwargs: Any) -> None:
+        self.out.print(*values, **kwargs)
+
+    def text(self, value: object) -> None:
+        """Print a value verbatim, with no markup interpretation."""
+        self.out.print(Text(str(value)))
+
+    def success(self, message: str) -> None:
+        self.out.print(f"[green]{message}[/green]")
+
+    def warning(self, message: str) -> None:
+        self.err.print(f"[yellow]{message}[/yellow]")
+
+    def error(self, message: str) -> None:
+        self.err.print(f"[red]error:[/red] {message}")
+
+    def hint(self, message: str) -> None:
+        self.err.print(f"[dim]{message}[/dim]")
+
+    def json(self, data: Any) -> None:
+        """Emit exact, machine-parseable JSON on stdout."""
+        payload = json.dumps(data, indent=2, ensure_ascii=False, default=_json_default)
+        self.out.print(payload, markup=False, highlight=False, soft_wrap=True)
+
+    def table(self, title: str | None, columns: Sequence[tuple[str, dict[str, Any]]]) -> Table:
+        table = Table(title=title, title_justify="left", header_style="bold")
+        for header, options in columns:
+            table.add_column(header, **options)
+        return table
+
+    @staticmethod
+    def cell(value: object) -> Text:
+        """Return a Rich cell that treats ``value`` as literal text."""
+        return Text(str(value))
+
+    def status(self, message: str) -> AbstractContextManager[Any]:
+        return self.out.status(message)
+
+    def render(self, *renderables: Iterable[Any] | Any) -> None:
+        for renderable in renderables:
+            self.out.print(renderable)
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, set | frozenset):
+        return sorted(value)
+    if hasattr(value, "__fspath__"):
+        return str(value)
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")

optforge/core/errors.py

@@ -0,0 +1,28 @@
+"""Exception hierarchy for expected, user-facing failures.
+
+Anything raised from this module is safe to show to a human: the message is
+written for a terminal, not for a stack trace. Unexpected exceptions are left
+alone so they keep their traceback.
+"""
+
+from __future__ import annotations
+
+
+class OptForgeError(Exception):
+    """Base class for every expected OptForge failure."""
+
+
+class PermissionDenied(OptForgeError):
+    """The operating system refused access to the requested resource."""
+
+
+class InvalidInput(OptForgeError):
+    """The caller supplied a value that cannot be used."""
+
+
+class NotFound(OptForgeError):
+    """The requested resource does not exist."""
+
+
+class OperationFailed(OptForgeError):
+    """An operation was attempted but could not be completed."""

optforge/core/formatting.py

@@ -0,0 +1,26 @@
+"""Small, dependency-free formatting helpers shared by the CLIs."""
+
+from __future__ import annotations
+
+_BINARY_UNITS = ("B", "KiB", "MiB", "GiB", "TiB", "PiB")
+
+
+def format_bytes(value: int | float) -> str:
+    """Render a byte count using binary units (1024-based).
+
+    >>> format_bytes(1536)
+    '1.50 KiB'
+    """
+    size = float(value)
+    unit = _BINARY_UNITS[0]
+    for candidate in _BINARY_UNITS:
+        unit = candidate
+        if abs(size) < 1024.0 or candidate == _BINARY_UNITS[-1]:
+            break
+        size /= 1024.0
+    return f"{size:.2f} {unit}"
+
+
+def format_percent(value: float, *, digits: int = 2) -> str:
+    """Render a percentage with a fixed number of decimal places."""
+    return f"{value:.{digits}f}%"

optforge/core/net.py

@@ -0,0 +1,87 @@
+"""Cross-platform socket address resolution.
+
+The standard library's ``socket.create_connection`` resolves names with an
+unbounded DNS call, which silently ignores a caller-supplied timeout. OptForge
+resolves addresses in a worker thread so the deadline is real, then connects to
+each returned endpoint with the remaining time.
+"""
+
+from __future__ import annotations
+
+import socket
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FuturesTimeoutError
+from dataclasses import dataclass
+from typing import Any
+
+from optforge.core.errors import OperationFailed
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    """One resolved socket address."""
+
+    family: int
+    sockaddr: tuple[Any, ...]
+
+    @property
+    def address(self) -> str:
+        return str(self.sockaddr[0])
+
+    @property
+    def port(self) -> int:
+        return int(self.sockaddr[1])
+
+    @property
+    def family_name(self) -> str:
+        return "ipv6" if self.family == socket.AF_INET6 else "ipv4"
+
+    def label(self) -> str:
+        if self.family == socket.AF_INET6:
+            return f"[{self.address}]:{self.port}"
+        return f"{self.address}:{self.port}"
+
+
+def resolve_endpoints(host: str, port: int, *, passive: bool = False) -> list[Endpoint]:
+    """Resolve ``host``/``port`` to every usable TCP endpoint.
+
+    Raises:
+        OperationFailed: if the name cannot be resolved.
+    """
+    flags = socket.AI_PASSIVE if passive else 0
+    try:
+        infos = socket.getaddrinfo(
+            host or None,
+            port,
+            type=socket.SOCK_STREAM,
+            flags=flags,
+        )
+    except socket.gaierror as exc:
+        reason = exc.strerror or str(exc)
+        raise OperationFailed(f"Could not resolve {host!r}: {reason}") from exc
+
+    endpoints: list[Endpoint] = []
+    seen: set[tuple[int, tuple[Any, ...]]] = set()
+    for family, _type, _proto, _canonname, sockaddr in infos:
+        key = (family, sockaddr)
+        if key in seen:
+            continue
+        seen.add(key)
+        endpoints.append(Endpoint(family=family, sockaddr=sockaddr))
+    if not endpoints:
+        raise OperationFailed(f"Could not resolve {host!r} to any TCP address.")
+    return endpoints
+
+
+def resolve_endpoints_with_timeout(host: str, port: int, timeout: float) -> list[Endpoint]:
+    """Resolve ``host`` while enforcing ``timeout`` on the DNS lookup."""
+    executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="optforge-dns")
+    future = executor.submit(resolve_endpoints, host, port)
+    try:
+        return future.result(timeout=timeout)
+    except FuturesTimeoutError as exc:
+        raise OperationFailed(
+            f"Timed out after {timeout:g}s while resolving {host!r}."
+        ) from exc
+    finally:
+        executor.shutdown(wait=False, cancel_futures=True)

optforge/core/processes.py

@@ -0,0 +1,38 @@
+"""Cached process-name lookups for socket owners."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import psutil
+
+_UNKNOWN = "-"
+
+
+class ProcessNameResolver:
+    """Resolve PIDs to names once, then serve from memory.
+
+    A busy machine can have hundreds of listening sockets owned by a handful of
+    processes. Looking each PID up on every scan is the difference between one
+    system call and hundreds.
+    """
+
+    def __init__(self, factory: Callable[[int], psutil.Process] = psutil.Process) -> None:
+        self._factory = factory
+        self._cache: dict[int, str] = {}
+
+    def name(self, pid: int | None) -> str:
+        if pid is None:
+            return _UNKNOWN
+        cached = self._cache.get(pid)
+        if cached is not None:
+            return cached
+        try:
+            resolved = self._factory(pid).name()
+        except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+            resolved = _UNKNOWN
+        self._cache[pid] = resolved
+        return resolved
+
+    def clear(self) -> None:
+        self._cache.clear()

optforge/core/redaction.py

@@ -0,0 +1,41 @@
+"""Key-based secret detection and redaction for environment inspection."""
+
+from __future__ import annotations
+
+import re
+
+_SECRET_KEY = re.compile(
+    r"(?:"
+    r"KEY|TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|CREDENTIAL|PRIVATE|"
+    r"AUTH|COOKIE|SESSION|SIGNATURE|CERT|DSN|DATABASE_URL|CONNECTION_STRING"
+    r")",
+    re.IGNORECASE,
+)
+
+DEFAULT_MASK = "<redacted>"
+
+
+class SecretRedactor:
+    """Decide whether an environment variable name is sensitive.
+
+    Detection is deliberately name-based and conservative: it errs toward
+    masking values that merely *look* like secrets, because a false positive is
+    cheap and a leaked token is not.
+    """
+
+    def __init__(self, mask: str = DEFAULT_MASK, pattern: re.Pattern[str] = _SECRET_KEY) -> None:
+        self._mask = mask
+        self._pattern = pattern
+
+    @property
+    def mask(self) -> str:
+        return self._mask
+
+    def is_sensitive(self, key: str) -> bool:
+        return bool(self._pattern.search(key))
+
+    def redact(self, key: str, value: str) -> tuple[str, bool]:
+        """Return ``(display_value, was_redacted)`` for ``key``/``value``."""
+        if self.is_sensitive(key):
+            return self._mask, True
+        return value, False

optforge/core/version.py

@@ -0,0 +1,15 @@
+"""Version resolution that works from an installed wheel and a source checkout."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+FALLBACK_VERSION = "0.2.0"
+
+
+def get_version(distribution: str = "optforge") -> str:
+    """Return the installed distribution version, or the source-tree fallback."""
+    try:
+        return version(distribution)
+    except PackageNotFoundError:
+        return FALLBACK_VERSION

optforge/diskcheck/__init__.py

@@ -0,0 +1,6 @@
+"""Inspect disk usage for a path or every mounted volume."""
+
+from optforge.diskcheck.models import DiskInfo
+from optforge.diskcheck.service import DiskService
+
+__all__ = ["DiskInfo", "DiskService"]

optforge/diskcheck/cli.py

@@ -0,0 +1,113 @@
+"""``diskcheck``: inspect disk usage and warn on storage pressure."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.text import Text
+
+from optforge.core.cli import ErrorBoundary, ExitCode
+from optforge.core.console import ConsoleIO
+from optforge.core.formatting import format_bytes, format_percent
+from optforge.core.version import get_version
+from optforge.diskcheck.models import DiskInfo
+from optforge.diskcheck.service import DiskService
+
+app = typer.Typer(
+    name="diskcheck",
+    help="Inspect disk usage and warn when storage pressure crosses a threshold.",
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = ConsoleIO()
+
+
+def _service() -> DiskService:
+    return DiskService()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"diskcheck (optforge {get_version()})")
+        raise typer.Exit()
+
+
+def _table(infos: list[DiskInfo], warn_at: float | None) -> None:
+    table = console.table(
+        "Disk usage",
+        [
+            ("Path", {"no_wrap": True}),
+            ("Total", {"justify": "right"}),
+            ("Used", {"justify": "right"}),
+            ("Free", {"justify": "right"}),
+            ("Used %", {"justify": "right"}),
+        ],
+    )
+    for info in infos:
+        pressure = warn_at is not None and info.percent_used >= warn_at
+        percent = Text(format_percent(info.percent_used), style="red" if pressure else "")
+        table.add_row(
+            console.cell(info.path),
+            format_bytes(info.total),
+            format_bytes(info.used),
+            format_bytes(info.free),
+            percent,
+        )
+    console.print(table)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    path: Annotated[str, typer.Argument(help="Directory or drive to inspect.")] = ".",
+    all_volumes: Annotated[
+        bool,
+        typer.Option("--all", "-a", help="Show every mounted volume instead of one path."),
+    ] = False,
+    warn_at: Annotated[
+        float | None,
+        typer.Option(
+            "--warn-at",
+            min=0.0,
+            max=100.0,
+            help="Exit 1 when used percent reaches this value.",
+        ),
+    ] = None,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON."),
+    ] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Show disk usage for a path or every mounted volume."""
+    with ErrorBoundary(console):
+        infos = _service().volumes() if all_volumes else [_service().usage(path)]
+
+    if as_json:
+        payload = [info.to_dict() for info in infos] if all_volumes else infos[0].to_dict()
+        console.json(payload)
+    else:
+        _table(infos, warn_at)
+
+    over_threshold = warn_at is not None and any(info.percent_used >= warn_at for info in infos)
+    if over_threshold:
+        if not as_json:
+            console.warning(
+                f"Storage pressure: at least one volume is at or above {warn_at:g}% used."
+            )
+        raise typer.Exit(ExitCode.NO)
+    raise typer.Exit(ExitCode.OK)
+
+
+if __name__ == "__main__":
+    app()

optforge/diskcheck/models.py

@@ -0,0 +1,31 @@
+"""Value objects for disk inspection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class DiskInfo:
+    """Usage for one path or mounted volume."""
+
+    path: str
+    total: int
+    used: int
+    free: int
+    percent_used: float
+
+    @property
+    def percent_free(self) -> float:
+        return 100.0 - self.percent_used
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "total": self.total,
+            "used": self.used,
+            "free": self.free,
+            "percent_used": round(self.percent_used, 2),
+            "percent_free": round(self.percent_free, 2),
+        }