forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/platform/__init__.py

@@ -0,0 +1,91 @@
+"""Cross-platform support layer for ForgeCLI.
+
+ForgeCLI must run identically on Windows 10/11, macOS (Intel and
+Apple Silicon) and Linux (Ubuntu, Fedora, Debian, Arch, Kali,
+openSUSE, etc.). This package is the *only* place where platform
+detection, dependency discovery, environment handling, and shell
+adaption live.
+
+The package is split into focused modules:
+
+* :mod:`forgecli.platform.core`     — OS detection + env helpers
+* :mod:`forgecli.platform.paths`    — config / data / cache dirs
+* :mod:`forgecli.platform.shell`    — shell adapter (no POSIX-only
+  hardcoding)
+* :mod:`forgecli.platform.deps`     — git / graphify / ponytail / python /
+  node / package-manager detection
+* :mod:`forgecli.platform.update`   — PyPI update check + version
+
+Downstream code must import from this package rather than from
+:mod:`sys` / :mod:`os` / :mod:`platform` directly.
+"""
+
+from forgecli.platform.core import (
+    OS,
+    Platform,
+    current_platform,
+    detect_os,
+    is_linux,
+    is_macos,
+    is_windows,
+    python_version,
+)
+from forgecli.platform.deps import (
+    DependencyReport,
+    DependencyStatus,
+    check_dependencies,
+    find_executable,
+    has_git,
+    has_graphify,
+    has_node,
+    has_ponytail,
+    has_python,
+    install_hint,
+)
+from forgecli.platform.paths import (
+    ProjectPaths,
+    config_dir,
+    data_dir,
+    load_dotenv,
+    state_dir,
+)
+from forgecli.platform.shell import ShellResult, run, shell_quote
+from forgecli.platform.update import (
+    UpdateInfo,
+    check_for_update,
+    current_version,
+    upgrade_command,
+)
+
+__all__ = [
+    "OS",
+    "DependencyReport",
+    "DependencyStatus",
+    "Platform",
+    "ProjectPaths",
+    "ShellResult",
+    "UpdateInfo",
+    "check_dependencies",
+    "check_for_update",
+    "config_dir",
+    "current_platform",
+    "current_version",
+    "data_dir",
+    "detect_os",
+    "find_executable",
+    "has_git",
+    "has_graphify",
+    "has_node",
+    "has_ponytail",
+    "has_python",
+    "install_hint",
+    "is_linux",
+    "is_macos",
+    "is_windows",
+    "load_dotenv",
+    "python_version",
+    "run",
+    "shell_quote",
+    "state_dir",
+    "upgrade_command",
+]

forgecli/platform/core.py

@@ -0,0 +1,201 @@
+"""OS detection + small environment helpers.
+
+All detection is a single :func:`detect_os` call, cached at module
+import time, and exposed via convenient predicates (:func:`is_linux`,
+:func:`is_macos`, :func:`is_windows`). The :data:`Platform` namedtuple
+also exposes ``arch`` (machine type), ``release`` (kernel/OS
+release), and a stable :data:`OS` enum.
+
+This module is the *only* place that imports :mod:`sys.platform` /
+:mod:`platform.machine` — everything else goes through
+:func:`current_platform`.
+"""
+
+from __future__ import annotations
+
+import os
+import platform as _platform
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from typing import Final
+
+
+class OS(str, Enum):
+    """Stable OS identifier.
+
+    We deliberately avoid :data:`sys.platform` strings in caller code;
+    only this module reads them.
+    """
+
+    LINUX = "linux"
+    MACOS = "macos"
+    WINDOWS = "windows"
+    OTHER = "other"
+
+
+@dataclass(frozen=True)
+class Platform:
+    """A snapshot of the runtime platform."""
+
+    os: OS
+    arch: str  # "x86_64" | "arm64" | "aarch64" | …
+    release: str  # kernel / OS release string
+    python: str  # "3.12.3"
+    is_wsl: bool = False
+
+    @property
+    def is_macos(self) -> bool:
+        return self.os is OS.MACOS
+
+    @property
+    def is_linux(self) -> bool:
+        return self.os is OS.LINUX
+
+    @property
+    def is_windows(self) -> bool:
+        return self.os is OS.WINDOWS
+
+    @property
+    def is_apple_silicon(self) -> bool:
+        return self.os is OS.MACOS and self.arch == "arm64"
+
+
+# A single cached snapshot taken at import time. Cheap; safe to use
+# in tight loops. The call below is intentionally *after* the function
+# definition so the module body executes top-to-bottom.
+def _build_platform() -> Platform:
+    sys_platform = sys.platform
+    if sys_platform.startswith("linux"):
+        os_value = OS.LINUX
+    elif sys_platform == "darwin":
+        os_value = OS.MACOS
+    elif sys_platform in {"win32", "cygwin"}:
+        os_value = OS.WINDOWS
+    else:
+        os_value = OS.OTHER
+
+    arch = _platform.machine() or "unknown"
+    # Normalise ARM naming on macOS.
+    if os_value is OS.MACOS and arch == "aarch64":
+        arch = "arm64"
+
+    release = ""
+    try:
+        if os_value is OS.WINDOWS:
+            release = _platform.win32_ver()[1] or _platform.release()
+        elif os_value is OS.MACOS:
+            release = _platform.mac_ver()[0] or _platform.release()
+        else:
+            release = _platform.release()
+    except Exception:
+        release = ""
+
+    is_wsl = False
+    if os_value is OS.LINUX:
+        try:
+            with open("/proc/version", encoding="utf-8", errors="replace") as fh:
+                head = fh.read(200).lower()
+            is_wsl = "microsoft" in head or "wsl" in head
+        except OSError:
+            is_wsl = False
+
+    return Platform(
+        os=os_value,
+        arch=arch,
+        release=release,
+        python=_platform.python_version(),
+        is_wsl=is_wsl,
+    )
+
+
+# A single cached snapshot taken at import time. Cheap; safe to use
+# in tight loops. The call below is intentionally *after* the function
+# definition so the module body executes top-to-bottom.
+_PLATFORM: Final[Platform] = _build_platform()
+
+
+def detect_os() -> OS:
+    """Return the current :class:`OS` value.
+
+    Equivalent to ``current_platform().os`` but slightly cheaper.
+    """
+    return _PLATFORM.os
+
+
+def current_platform() -> Platform:
+    """Return the cached :class:`Platform` snapshot."""
+    return _PLATFORM
+
+
+def is_windows() -> bool:
+    return _PLATFORM.os is OS.WINDOWS
+
+
+def is_macos() -> bool:
+    return _PLATFORM.os is OS.MACOS
+
+
+def is_linux() -> bool:
+    return _PLATFORM.os is OS.LINUX
+
+
+def python_version() -> str:
+    """Return the running Python version (``'3.12.3'``)."""
+    return _PLATFORM.python
+
+
+# ---------------------------------------------------------------------------
+# Environment helpers
+# ---------------------------------------------------------------------------
+
+
+def getenv(name: str, default: str | None = None) -> str | None:
+    """Read an environment variable, returning ``default`` if missing."""
+    return os.environ.get(name, default)
+
+
+def getenv_bool(name: str, default: bool = False) -> bool:
+    """Parse a boolean environment variable.
+
+    Truthy: ``"1"``, ``"true"``, ``"yes"``, ``"on"`` (case-insensitive).
+    Falsy: ``"0"``, ``"false"``, ``"no"``, ``"off"``, ``""``.
+    """
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def getenv_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or raw.strip() == "":
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def getenv_list(name: str, default: tuple[str, ...] = (), *, sep: str = ",") -> tuple[str, ...]:
+    """Parse a delimited environment variable as a tuple of strings."""
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return tuple(part.strip() for part in raw.split(sep) if part.strip())
+
+
+__all__ = [
+    "OS",
+    "Platform",
+    "current_platform",
+    "detect_os",
+    "getenv",
+    "getenv_bool",
+    "getenv_int",
+    "getenv_list",
+    "is_linux",
+    "is_macos",
+    "is_windows",
+    "python_version",
+]

forgecli/platform/deps.py

@@ -0,0 +1,361 @@
+"""Dependency detection + install guidance.
+
+The :class:`DependencyReport` aggregates the status of every
+optional / required external tool ForgeCLI integrates with:
+
+* ``git``        — required (we have a ``git`` adapter regardless)
+* ``python``     — the running interpreter
+* ``ponytail``   — **built-in**; the ruleset optimizer ships with
+  ForgeCLI — no external binary required
+* ``graphify``   — optional; powers the knowledge graph
+  (install via ``uv tool install graphifyy``)
+* ``node``       — optional; needed by some LLM providers
+* ``pip`` / ``uv`` / ``brew`` / ``scoop`` / ``winget`` — package
+  managers used to render install hints.
+
+Each dependency is :class:`DependencyStatus` (found / missing /
+version). :func:`check_dependencies` returns a report; callers can
+serialize it for ``forge doctor`` output.
+
+Install hints are platform-aware: a missing ``graphify`` on macOS
+gets a ``brew install graphify`` line; on Windows, a
+``winget install Graphify.Graphify`` line; on Ubuntu, an
+``apt``/``snap`` line. We never suggest a Linux command when
+``is_windows()`` is True.
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Final
+
+from forgecli.platform.core import (
+    OS,
+    current_platform,
+    is_macos,
+    is_windows,
+    python_version,
+)
+
+
+class DependencyStatus(str, Enum):
+    """The result of probing a single external tool."""
+
+    FOUND = "found"
+    MISSING = "missing"
+    UNAVAILABLE = "unavailable"  # not supported on this platform
+
+
+@dataclass(frozen=True)
+class Dependency:
+    """One external tool that ForgeCLI may need."""
+
+    name: str
+    status: DependencyStatus
+    path: str | None = None
+    version: str | None = None
+    required: bool = False
+    note: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "status": self.status.value,
+            "path": self.path,
+            "version": self.version,
+            "required": self.required,
+            "note": self.note,
+        }
+
+
+@dataclass(frozen=True)
+class DependencyReport:
+    """A snapshot of every dependency ForgeCLI cares about."""
+
+    dependencies: tuple[Dependency, ...] = field(default_factory=tuple)
+
+    @property
+    def missing(self) -> tuple[Dependency, ...]:
+        return tuple(d for d in self.dependencies if d.status is DependencyStatus.MISSING)
+
+    @property
+    def missing_required(self) -> tuple[Dependency, ...]:
+        return tuple(
+            d for d in self.dependencies if d.status is DependencyStatus.MISSING and d.required
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "platform": current_platform().os.value,
+            "arch": current_platform().arch,
+            "python": python_version(),
+            "dependencies": [d.to_dict() for d in self.dependencies],
+            "missing": [d.name for d in self.missing],
+            "missing_required": [d.name for d in self.missing_required],
+        }
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+
+def find_executable(name: str) -> str | None:
+    """Return the absolute path of ``name`` if it's on PATH, else None."""
+    return shutil.which(name)
+
+
+def has_git() -> bool:
+    return find_executable("git") is not None
+
+
+def has_python() -> bool:
+    """Always True (we're running inside Python), but exposed for symmetry."""
+    return True
+
+
+def has_graphify() -> bool:
+    return find_executable("graphify") is not None
+
+
+def has_ponytail() -> bool:
+    return find_executable("ponytail") is not None
+
+
+def has_node() -> bool:
+    return find_executable("node") is not None
+
+
+def has_pip() -> bool:
+    return find_executable("pip") is not None or find_executable("pip3") is not None
+
+
+def has_uv() -> bool:
+    return find_executable("uv") is not None
+
+
+def has_homebrew() -> bool:
+    return find_executable("brew") is not None
+
+
+def has_scoop() -> bool:
+    return find_executable("scoop") is not None
+
+
+def has_winget() -> bool:
+    return find_executable("winget") is not None
+
+
+# ---------------------------------------------------------------------------
+# Version probe
+# ---------------------------------------------------------------------------
+
+
+def _run_version(executable: str, args: tuple[str, ...] = ("--version",)) -> str | None:
+    """Run ``executable --version`` and return the captured stdout."""
+    path = find_executable(executable)
+    if path is None:
+        return None
+    try:
+        completed = __import__("subprocess").run(
+            [path, *args],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, __import__("subprocess").TimeoutExpired):
+        return None
+    out = (completed.stdout or completed.stderr or "").strip()
+    # Trim to first line; strip noise like "git version 2.39.0".
+    return out.splitlines()[0] if out else None
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+
+def check_dependencies() -> DependencyReport:
+    """Return a structured :class:`DependencyReport` for the current host."""
+    deps: list[Dependency] = []
+
+    deps.append(_probe_required("git", has_git, _version_for("git")))
+    deps.append(_probe_required("python", has_python, lambda: python_version()))
+    # Ponytail is built-in — the PonytailRulesetOptimizer ships with
+    # ForgeCLI and requires no external binary.
+    deps.append(
+        Dependency(
+            name="ponytail",
+            status=DependencyStatus.FOUND,
+            version="built-in",
+            required=False,
+            note="Ruleset optimizer ships with ForgeCLI (no external binary needed)",
+        )
+    )
+    deps.append(
+        _probe_optional(
+            "graphify",
+            has_graphify,
+            _version_for("graphify"),
+            note="Optional. Install with: uv tool install graphifyy",
+        )
+    )
+    deps.append(_probe_optional("node", has_node, _version_for("node")))
+    deps.append(_probe_optional("pip", has_pip, _version_for("pip")))
+    deps.append(_probe_optional("uv", has_uv, _version_for("uv")))
+
+    # Package managers (platform-specific).
+    if is_windows():
+        deps.append(_probe_optional("scoop", has_scoop, _version_for("scoop")))
+        deps.append(_probe_optional("winget", has_winget, _version_for("winget")))
+    elif is_macos():
+        deps.append(_probe_optional("brew", has_homebrew, _version_for("brew")))
+
+    return DependencyReport(dependencies=tuple(deps))
+
+
+def _version_for(executable: str):
+    """Return a zero-arg callable that fetches the version of ``executable``."""
+
+    def _callable() -> str | None:
+        return _run_version(executable)
+
+    return _callable
+
+
+def _probe_required(
+    name: str,
+    has: Callable[[], bool],
+    version: Callable[[], str | None],
+    *,
+    note: str | None = None,
+) -> Dependency:
+    if has():
+        return Dependency(
+            name=name,
+            status=DependencyStatus.FOUND,
+            path=find_executable(name),
+            version=version(),
+            required=True,
+            note=note,
+        )
+    return Dependency(
+        name=name,
+        status=DependencyStatus.MISSING,
+        required=True,
+        note=note or "required by ForgeCLI",
+    )
+
+
+def _probe_optional(
+    name: str,
+    has: Callable[[], bool],
+    version: Callable[[], str | None],
+    *,
+    note: str | None = None,
+) -> Dependency:
+    if has():
+        return Dependency(
+            name=name,
+            status=DependencyStatus.FOUND,
+            path=find_executable(name),
+            version=version(),
+            required=False,
+            note=note,
+        )
+    return Dependency(
+        name=name,
+        status=DependencyStatus.MISSING,
+        required=False,
+        note=note,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Install hints
+# ---------------------------------------------------------------------------
+
+
+_HINTS: Final[dict[str, dict[OS, tuple[str, ...]]]] = {
+    "graphify": {
+        OS.LINUX: (
+            "uv tool install graphifyy",
+            "or:  pipx install graphifyy",
+            "or:  pip install --user graphifyy",
+        ),
+        OS.MACOS: (
+            "brew install graphifyy",
+            "or:  uv tool install graphifyy",
+        ),
+        OS.WINDOWS: (
+            "winget install graphifyy",
+            "or:  scoop install graphifyy",
+            "or:  uv tool install graphifyy",
+        ),
+        OS.OTHER: ("uv tool install graphifyy",),
+    },
+    "ponytail": {
+        # Ponytail is built-in; an external CLI is only used when the
+        # user explicitly sets backend=cli in forgecli.toml.
+        OS.LINUX: ("Built-in — no install needed. External CLI: uv tool install ponytail",),
+        OS.MACOS: ("Built-in — no install needed. External CLI: uv tool install ponytail",),
+        OS.WINDOWS: ("Built-in — no install needed. External CLI: uv tool install ponytail",),
+        OS.OTHER: ("Built-in — no install needed.",),
+    },
+    "git": {
+        OS.LINUX: (
+            "sudo apt install git          (Debian / Ubuntu)",
+            "sudo dnf install git          (Fedora)",
+            "sudo pacman -S git            (Arch)",
+            "sudo zypper install git       (openSUSE)",
+        ),
+        OS.MACOS: ("xcode-select --install   (or:  brew install git)",),
+        OS.WINDOWS: ("winget install Git.Git", "or:  scoop install git"),
+        OS.OTHER: ("install Git from your package manager",),
+    },
+    "node": {
+        OS.LINUX: (
+            "sudo apt install nodejs      (Debian / Ubuntu)",
+            "or:  https://nodejs.org/en/download",
+        ),
+        OS.MACOS: ("brew install node", "or:  https://nodejs.org/en/download"),
+        OS.WINDOWS: ("winget install OpenJS.NodeJS", "or:  scoop install nodejs"),
+        OS.OTHER: ("install Node.js from https://nodejs.org",),
+    },
+}
+
+
+def install_hint(tool: str) -> tuple[str, ...]:
+    """Return the install lines for ``tool`` on the current platform."""
+    key = tool.lower().strip()
+    table = _HINTS.get(key, {})
+    if not table:
+        return (f"see the {tool} project documentation for install instructions",)
+    return table.get(current_platform().os, table[OS.OTHER])
+
+
+__all__ = [
+    "Dependency",
+    "DependencyReport",
+    "DependencyStatus",
+    "check_dependencies",
+    "find_executable",
+    "has_git",
+    "has_graphify",
+    "has_homebrew",
+    "has_node",
+    "has_pip",
+    "has_ponytail",
+    "has_python",
+    "has_scoop",
+    "has_uv",
+    "has_winget",
+    "install_hint",
+]
+
+
+# Silence unused-import warnings.