optforge 0.2.0__py3-none-any.whl

optforge/diskcheck/service.py

@@ -0,0 +1,56 @@
+"""Disk usage collection for a path or every mounted volume."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from collections.abc import Callable, Iterable
+from typing import Any
+
+import psutil
+
+from optforge.core.errors import OperationFailed, OptForgeError
+from optforge.diskcheck.models import DiskInfo
+
+UsageReader = Callable[[str], tuple[int, int, int]]
+PartitionReader = Callable[..., Iterable[Any]]
+
+
+class DiskService:
+    """Read usage without crashing on one unreadable mount."""
+
+    def __init__(
+        self,
+        usage: UsageReader = shutil.disk_usage,
+        partitions: PartitionReader = psutil.disk_partitions,
+    ) -> None:
+        self._usage = usage
+        self._partitions = partitions
+
+    def usage(self, path: str = ".") -> DiskInfo:
+        """Return usage for ``path``."""
+        try:
+            total, used, free = self._usage(path)
+        except OSError as exc:
+            raise OperationFailed(f"Could not read disk usage for {path!r}: {exc}") from exc
+        percent_used = (used / total * 100.0) if total else 0.0
+        return DiskInfo(
+            path=os.path.abspath(path),
+            total=int(total),
+            used=int(used),
+            free=int(free),
+            percent_used=float(percent_used),
+        )
+
+    def volumes(self) -> list[DiskInfo]:
+        """Return usage for every mounted partition that can be read."""
+        results: list[DiskInfo] = []
+        for partition in self._partitions(all=True):
+            mountpoint = getattr(partition, "mountpoint", None)
+            if not mountpoint:
+                continue
+            try:
+                results.append(self.usage(mountpoint))
+            except OptForgeError:
+                continue
+        return results

optforge/envcheck/__init__.py

@@ -0,0 +1,6 @@
+"""Inspect environment variables without leaking secrets."""
+
+from optforge.envcheck.models import EnvEntry, OutputFormat
+from optforge.envcheck.service import EnvironmentService
+
+__all__ = ["EnvEntry", "EnvironmentService", "OutputFormat"]

optforge/envcheck/cli.py

@@ -0,0 +1,102 @@
+"""``envcheck``: inspect environment variables without leaking secrets."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.text import Text
+
+from optforge.core.cli import ErrorBoundary
+from optforge.core.console import ConsoleIO
+from optforge.core.version import get_version
+from optforge.envcheck.models import EnvEntry, OutputFormat
+from optforge.envcheck.service import EnvironmentService
+
+app = typer.Typer(
+    name="envcheck",
+    help="Inspect environment variables and runtime configuration. Secrets are redacted by default.",
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = ConsoleIO()
+
+
+def _service() -> EnvironmentService:
+    return EnvironmentService()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"envcheck (optforge {get_version()})")
+        raise typer.Exit()
+
+
+def _render_table(entries: list[EnvEntry]) -> None:
+    table = console.table(
+        "Environment variables",
+        [("Key", {"style": "cyan", "no_wrap": True}), ("Value", {})],
+    )
+    for entry in entries:
+        value = Text(entry.value, style="yellow" if entry.redacted else "")
+        table.add_row(console.cell(entry.key), value)
+    console.print(table)
+    if any(entry.redacted for entry in entries):
+        console.hint("Sensitive values are masked. Pass --show-secrets to reveal them.")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    prefix: Annotated[
+        str | None,
+        typer.Option("--prefix", "-p", help="Only show variables starting with this prefix."),
+    ] = None,
+    include_hidden: Annotated[
+        bool,
+        typer.Option(
+            "--include-hidden/--no-include-hidden",
+            help="Include variables whose names begin with an underscore.",
+        ),
+    ] = True,
+    show_secrets: Annotated[
+        bool,
+        typer.Option("--show-secrets", help="Reveal values that look sensitive."),
+    ] = False,
+    output: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", case_sensitive=False, help="Output format."),
+    ] = OutputFormat.table,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Alias for --format json.")
+    ] = False,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """List environment variables, redacting secrets by default."""
+    with ErrorBoundary(console):
+        entries = _service().entries(
+            prefix=prefix,
+            include_hidden=include_hidden,
+            redact=not show_secrets,
+        )
+
+    chosen = OutputFormat.json if as_json else output
+    if chosen is OutputFormat.json:
+        console.json([entry.to_dict() for entry in entries])
+    elif chosen is OutputFormat.dotenv:
+        console.text(_service().to_dotenv(entries))
+    else:
+        _render_table(entries)
+
+
+if __name__ == "__main__":
+    app()

optforge/envcheck/models.py

@@ -0,0 +1,33 @@
+"""Value objects for environment inspection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class OutputFormat(str, Enum):
+    """Supported ``envcheck`` output formats."""
+
+    table = "table"
+    json = "json"
+    dotenv = "dotenv"
+
+
+@dataclass(frozen=True, slots=True)
+class EnvEntry:
+    """One environment variable, optionally redacted."""
+
+    key: str
+    value: str
+    sensitive: bool = False
+    redacted: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "value": self.value,
+            "sensitive": self.sensitive,
+            "redacted": self.redacted,
+        }

optforge/envcheck/service.py

@@ -0,0 +1,66 @@
+"""Environment variable collection and redaction."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from optforge.core.redaction import SecretRedactor
+from optforge.envcheck.models import EnvEntry
+
+_QUOTE_TRIGGERS = frozenset(' \t\n#"\'')
+
+
+class EnvironmentService:
+    """Read ``os.environ`` and decide what is safe to display."""
+
+    def __init__(
+        self,
+        environ: Mapping[str, str] | None = None,
+        redactor: SecretRedactor | None = None,
+    ) -> None:
+        self._environ = environ if environ is not None else os.environ
+        self._redactor = redactor or SecretRedactor()
+
+    def entries(
+        self,
+        *,
+        prefix: str | None = None,
+        include_hidden: bool = True,
+        redact: bool = True,
+    ) -> list[EnvEntry]:
+        """Return sorted entries, masking sensitive values by default."""
+        needle = prefix.lower() if prefix else None
+        entries: list[EnvEntry] = []
+        for key in sorted(self._environ):
+            if needle is not None and not key.lower().startswith(needle):
+                continue
+            if not include_hidden and key.startswith("_"):
+                continue
+            raw = self._environ[key]
+            sensitive = self._redactor.is_sensitive(key)
+            value = raw
+            redacted = False
+            if redact and sensitive:
+                value, redacted = self._redactor.redact(key, raw)
+            entries.append(
+                EnvEntry(key=key, value=value, sensitive=sensitive, redacted=redacted)
+            )
+        return entries
+
+    @staticmethod
+    def to_dotenv(entries: list[EnvEntry]) -> str:
+        """Render entries as a ``.env`` fragment."""
+        return "\n".join(_dotenv_line(entry) for entry in entries)
+
+
+def _dotenv_line(entry: EnvEntry) -> str:
+    if not entry.value or not (set(entry.value) & _QUOTE_TRIGGERS):
+        return f"{entry.key}={entry.value}"
+    escaped = (
+        entry.value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\t", "\\t")
+    )
+    return f'{entry.key}="{escaped}"'

optforge/killNotif/cli.py

@@ -0,0 +1,110 @@
+"""``killNotif``: clear Windows toast notifications.
+
+Exit codes
+    0  the command ran successfully (even when nothing needed clearing)
+    2  invalid usage (raised by Typer)
+    3  the operation could not run (wrong OS, missing helper, PowerShell error)
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+import typer
+from rich.text import Text
+
+from optforge.core.cli import ErrorBoundary
+from optforge.core.console import ConsoleIO
+from optforge.core.errors import OperationFailed
+from optforge.core.version import get_version
+
+app = typer.Typer(
+    name="killNotif",
+    help="Clear Windows toast notifications, optionally for a single app.",
+    epilog="Exit codes: 0 ok | 2 bad usage | 3 could not run",
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+console = ConsoleIO()
+
+AumidOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--aumid",
+        "-a",
+        metavar="AUMID",
+        help="Only clear notifications from this AppUserModelID.",
+    ),
+]
+QuietOpt = Annotated[
+    bool, typer.Option("--quiet", "-q", help="Print nothing; use the exit code only.")
+]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"killNotif (optforge {get_version()})")
+        raise typer.Exit()
+
+
+def _clear(aumid: str | None) -> int:
+    """Import lazily so ``--help`` and ``--version`` stay fast."""
+    from optforge.killNotif.core import clear_notifications
+
+    return clear_notifications(aumid)
+
+
+def _run(aumid: str | None) -> int:
+    if sys.platform != "win32":
+        raise OperationFailed("killNotif requires Windows 10/11 (WinRT toast history).")
+
+    try:
+        return _clear(aumid)
+    except FileNotFoundError as exc:
+        raise OperationFailed(f"{exc} Ensure PowerShell 5.1+ is installed.") from exc
+    except RuntimeError as exc:
+        raise OperationFailed(str(exc)) from exc
+    except ValueError as exc:
+        raise OperationFailed(f"unexpected helper output: {exc}") from exc
+
+
+@app.command()
+def main(
+    aumid: AumidOpt = None,
+    json_output: JsonOpt = False,
+    quiet: QuietOpt = False,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Clear toast notifications from the Windows Action Center."""
+    target = aumid.strip() if aumid else None
+
+    with ErrorBoundary(console):
+        cleared = _run(target)
+
+    if quiet:
+        return
+    if json_output:
+        console.json({"aumid": target, "cleared": cleared})
+        return
+    if cleared == 0:
+        console.print(Text("No notifications to clear.", style="dim"))
+    elif target:
+        console.print(Text(f"Cleared {cleared} sender(s) matching {target}.", style="green"))
+    else:
+        console.print(Text(f"Cleared {cleared} sender(s).", style="green"))
+
+
+if __name__ == "__main__":
+    app()

optforge/killNotif/core.py

@@ -0,0 +1,24 @@
+import subprocess
+from pathlib import Path
+
+JOB = Path(__file__).with_name("job.ps1")
+
+
+def clear_notifications(aumid: str | None = None) -> int:
+    """Clear all notifications (or one sender's). Returns senders cleared."""
+    if not JOB.exists():
+        raise FileNotFoundError(f"helper script missing: {JOB}")
+
+    cmd = [
+        "powershell", "-NoProfile", "-NonInteractive",
+        "-ExecutionPolicy", "Bypass", "-File", str(JOB),
+    ]
+    if aumid:
+        cmd += ["-Aumid", aumid]
+
+    res = subprocess.run(cmd, capture_output=True, text=True)
+    if res.returncode != 0:
+        raise RuntimeError((res.stderr or res.stdout).strip() or "job.ps1 failed")
+
+    out = res.stdout.strip().splitlines()[-1] if res.stdout.strip() else "0"
+    return int(out)

optforge/killNotif/job.ps1

@@ -0,0 +1,52 @@
+#Requires -Version 5.1
+[CmdletBinding()]
+param(
+    [string]$Aumid   # optional: clear only this sender; empty = all
+)
+
+$ErrorActionPreference = 'Stop'
+
+try {
+    [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] | Out-Null
+} catch {
+    Write-Error "WinRT notification API unavailable (not Windows 10/11?)"
+    exit 2
+}
+
+$history = [Windows.UI.Notifications.ToastNotificationManager]::History
+
+if ($Aumid) {
+    $targets = @($Aumid)
+} else {
+    $key = 'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Notifications\Settings'
+    if (-not (Test-Path $key)) {
+        Write-Output 0
+        exit 0
+    }
+
+    $targets = @(
+        Get-ChildItem -Path $key -ErrorAction Stop |
+            ForEach-Object { $_.PSChildName }
+    )
+}
+
+$cleared = 0
+foreach ($target in $targets) {
+    if ([string]::IsNullOrWhiteSpace($target)) {
+        continue
+    }
+
+    try {
+        $items = $history.GetHistory($target)
+        if (@($items).Count -eq 0) {
+            continue
+        }
+
+        $history.Clear($target)
+        $cleared++
+    } catch {
+        Write-Warning "Could not clear notifications for '$target': $($_.Exception.Message)"
+    }
+}
+
+Write-Output $cleared

optforge/portcheck/__init__.py

@@ -0,0 +1,14 @@
+"""Inspect listening TCP ports and test connectivity."""
+
+from optforge.portcheck.models import CheckResult, ConnectResult, Listener, PortState, SortKey, WaitResult
+from optforge.portcheck.service import PortService
+
+__all__ = [
+    "CheckResult",
+    "ConnectResult",
+    "Listener",
+    "PortService",
+    "PortState",
+    "SortKey",
+    "WaitResult",
+]

optforge/portcheck/binder.py

@@ -0,0 +1,72 @@
+"""Bind probes that answer "can this host:port be bound right now?"."""
+
+from __future__ import annotations
+
+import os
+import socket
+
+from optforge.core.errors import OperationFailed
+from optforge.core.net import Endpoint, resolve_endpoints
+
+_WILDCARD_HOSTS = frozenset({"", "*", "any", "all"})
+
+
+class PortBinder:
+    """Test bindability without leaving a socket behind.
+
+    Notes:
+        * POSIX sets ``SO_REUSEADDR`` so a socket in ``TIME_WAIT`` does not make
+          a genuinely free port look busy.
+        * Windows sets ``SO_EXCLUSIVEADDRUSE`` instead; ``SO_REUSEADDR`` on
+          Windows lets two processes bind the same port, which is exactly the
+          bug this tool exists to detect.
+        * A successful probe is inherently racy: another process may take the
+          port after the probe closes. Callers must treat the answer as a
+          snapshot.
+    """
+
+    def __init__(self, default_host: str = "0.0.0.0") -> None:
+        self._default_host = default_host
+
+    def is_free(self, port: int, host: str | None = None) -> bool:
+        """Return ``True`` only if every resolved address for the host binds."""
+        endpoints = self._endpoints(port, host or self._default_host)
+        if not endpoints:
+            return True
+        return all(self._can_bind(endpoint) for endpoint in endpoints)
+
+    def is_free_on_all_interfaces(self, port: int) -> bool:
+        """Return ``True`` if both the IPv4 and IPv6 wildcard addresses bind."""
+        return self.is_free(port, "0.0.0.0") and self.is_free(port, "::")
+
+    def _endpoints(self, port: int, host: str) -> list[Endpoint]:
+        target = None if host.lower() in _WILDCARD_HOSTS else host
+        try:
+            return resolve_endpoints(target or "", port, passive=True)
+        except OperationFailed:
+            # No address of this family exists on the machine (for example IPv6
+            # is disabled). There is nothing to bind, so it cannot be occupied.
+            return []
+
+    def _can_bind(self, endpoint: Endpoint) -> bool:
+        try:
+            sock = socket.socket(endpoint.family, socket.SOCK_STREAM)
+        except OSError:
+            return False
+        try:
+            self._configure(sock)
+            sock.bind(endpoint.sockaddr)
+            return True
+        except OSError:
+            return False
+        finally:
+            sock.close()
+
+    @staticmethod
+    def _configure(sock: socket.socket) -> None:
+        if os.name == "nt":
+            exclusive = getattr(socket, "SO_EXCLUSIVEADDRUSE", None)
+            if exclusive is not None:
+                sock.setsockopt(socket.SOL_SOCKET, exclusive, 1)
+            return
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)