forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/platform/paths.py

@@ -0,0 +1,236 @@
+"""Cross-platform paths, env files, and config directory resolution.
+
+* :class:`ProjectPaths` — a typed bundle of well-known paths
+  (config, data, cache, log, prompts, plugins) computed from
+  environment variables with sensible XDG-style defaults via
+  :mod:`platformdirs`.
+* :func:`load_dotenv` — a minimal ``.env`` loader that does **not**
+  overwrite existing environment variables.
+* :func:`config_dir` / :func:`data_dir` / :func:`state_dir` — single
+  helpers for callers that only need one path.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from forgecli.platform.core import (
+    is_macos,
+    is_windows,
+)
+
+# ---------------------------------------------------------------------------
+# Directory helpers
+# ---------------------------------------------------------------------------
+
+
+def _xdg_path(env_var: str, *fallback: Path) -> Path:
+    """Return ``$env_var`` if set, else the first existing ``fallback``."""
+    value = os.environ.get(env_var)
+    if value:
+        return Path(value).expanduser()
+    for candidate in fallback:
+        if candidate.exists():
+            return candidate
+    return fallback[0]
+
+
+def config_dir() -> Path:
+    """Return the per-user config directory for ForgeCLI.
+
+    Honors ``FORGECLI_CONFIG_DIR`` and the platform-standard
+    XDG / Apple / Windows variables (``XDG_CONFIG_HOME`` /
+    ``HOME`` / ``APPDATA``). Creates the directory if missing.
+    """
+    if is_windows():
+        base = Path(os.environ.get("APPDATA") or (Path.home() / "AppData" / "Roaming"))
+    elif is_macos():
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = _xdg_path("XDG_CONFIG_HOME", Path.home() / ".config")
+    path = base / "forgecli"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def data_dir() -> Path:
+    """Return the per-user data directory for ForgeCLI."""
+    override = _coerce_path("FORGECLI_DATA_DIR")
+    if override is not None:
+        return override
+    if is_windows():
+        base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+    elif is_macos():
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = _xdg_path("XDG_DATA_HOME", Path.home() / ".local" / "share")
+    path = base / "forgecli"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def state_dir() -> Path:
+    """Return the per-user state directory (logs, caches)."""
+    if is_windows():
+        base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+    elif is_macos():
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = _xdg_path("XDG_STATE_HOME", Path.home() / ".local" / "state")
+    path = base / "forgecli"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+# ---------------------------------------------------------------------------
+# .env loader
+# ---------------------------------------------------------------------------
+
+
+def load_dotenv(
+    path: Path | str | None = None,
+    *,
+    override: bool = False,
+    encoding: str = "utf-8",
+) -> dict[str, str]:
+    """Load a ``.env`` file into :data:`os.environ`.
+
+    Returns the dict of *new* (or *overridden*) variables. Existing
+    environment variables are preserved unless ``override=True``.
+
+    Comments (``#``) and blank lines are skipped. Quoted values are
+    stripped; whitespace around the ``=`` is trimmed.
+    """
+    candidate = Path(path) if path is not None else Path.cwd() / ".env"
+    if not candidate.exists():
+        return {}
+    try:
+        text = candidate.read_text(encoding=encoding, errors="replace")
+    except OSError:
+        return {}
+
+    loaded: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        # Strip a single layer of matching quotes.
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+            value = value[1:-1]
+        if not key:
+            continue
+        if key in os.environ and not override:
+            continue
+        os.environ[key] = value
+        loaded[key] = value
+    return loaded
+
+
+# ---------------------------------------------------------------------------
+# ProjectPaths
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProjectPaths:
+    """All well-known filesystem locations for ForgeCLI."""
+
+    cwd: Path
+    config_dir: Path
+    data_dir: Path
+    cache_dir: Path
+    logs_dir: Path
+    prompts_dir: Path
+    plugins_dir: Path
+
+    @classmethod
+    def from_env(
+        cls, *, cwd: Path | str | None = None
+    ) -> ProjectPaths:
+        """Resolve the default project paths for the current user.
+
+        Environment variables take precedence: ``FORGECLI_DATA_DIR``,
+        ``FORGECLI_CONFIG_DIR``, ``FORGECLI_CACHE_DIR``.
+        """
+        config = _coerce_path("FORGECLI_CONFIG_DIR") or config_dir()
+        data = _coerce_path("FORGECLI_DATA_DIR") or data_dir()
+        cache = _coerce_path("FORGECLI_CACHE_DIR") or _cache_dir()
+        logs = data / "logs"
+        prompts = config / "prompts"
+        plugins = config / "plugins"
+        for path in (config, data, cache, logs, prompts, plugins):
+            path.mkdir(parents=True, exist_ok=True)
+        return cls(
+            cwd=Path(cwd) if cwd is not None else Path.cwd(),
+            config_dir=config,
+            data_dir=data,
+            cache_dir=cache,
+            logs_dir=logs,
+            prompts_dir=prompts,
+            plugins_dir=plugins,
+        )
+
+
+def _cache_dir() -> Path:
+    """Return the cache directory, creating it if needed."""
+    if is_windows():
+        base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+    elif is_macos():
+        base = Path.home() / "Library" / "Caches"
+    else:
+        base = _xdg_path("XDG_CACHE_HOME", Path.home() / ".cache")
+    path = base / "forgecli"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _coerce_path(env_var: str) -> Path | None:
+    raw = os.environ.get(env_var)
+    if raw is None or raw.strip() == "":
+        return None
+    path = Path(raw).expanduser()
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Tiny utilities
+# ---------------------------------------------------------------------------
+
+
+def ensure_directory(path: Path | str) -> Path:
+    """Create ``path`` (and parents) if it does not exist; return it."""
+    p = Path(path).expanduser()
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def merge_paths(*paths: Path | str) -> Path:
+    """Return ``paths[0] / paths[1] / ... / paths[-1]`` as a :class:`Path`."""
+    if not paths:
+        raise ValueError("merge_paths requires at least one path")
+    out = Path(paths[0])
+    for tail in paths[1:]:
+        out = out / tail
+    return out
+
+
+__all__ = [
+    "ProjectPaths",
+    "config_dir",
+    "data_dir",
+    "ensure_directory",
+    "load_dotenv",
+    "merge_paths",
+    "state_dir",
+]
+
+
+# Silence unused-import warnings.

forgecli/platform/shell.py

@@ -0,0 +1,176 @@
+"""Shell adapter — never hardcodes POSIX-only commands.
+
+This module is the *only* place that may invoke
+:func:`subprocess.run` / :func:`asyncio.create_subprocess_shell` for
+shell-style invocations. All callers go through :func:`run`, which:
+
+* never relies on ``/bin/sh`` parsing on Windows (it uses
+  :class:`subprocess.Popen` with ``shell=False`` and a list argv);
+* quotes arguments via :func:`shell_quote` (which understands
+  POSIX shells *and* ``cmd.exe`` quoting rules);
+* enforces a timeout;
+* returns a :class:`ShellResult` that captures stdout/stderr
+  decoded as UTF-8 (with replacement) — never ``bytes`` leaking
+  out of the platform layer.
+
+The module also exposes a small ``run_capture`` helper used by
+:mod:`forgecli.graph.client` and friends.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shlex
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from forgecli.platform.core import is_windows
+
+
+@dataclass(frozen=True)
+class ShellResult:
+    """The structured output of a shell invocation."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+    command: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def shell_quote(arg: str) -> str:
+    """Quote ``arg`` for the current platform's shell.
+
+    On POSIX we use :func:`shlex.quote`; on Windows we use
+    :func:`subprocess.list2cmdline` (the same algorithm ``cmd.exe``
+    uses internally for argv joining).
+    """
+    if is_windows():
+        # list2cmdline accepts a list, not a single string. We wrap the
+        # single arg in a list.
+        return subprocess.list2cmdline([arg])
+    return shlex.quote(arg)
+
+
+def run(
+    args: Sequence[str] | str,
+    *,
+    cwd: Path | str | None = None,
+    env: dict[str, str] | None = None,
+    timeout: float | None = None,
+    check: bool = False,
+    input: str | bytes | None = None,
+) -> ShellResult:
+    """Run a subprocess and return a :class:`ShellResult`.
+
+    ``args`` may be either a list (preferred — avoids shell parsing
+    entirely) or a string (in which case the call goes through
+    the platform's default shell).
+
+    On Windows, ``args`` is always coerced to a list to avoid
+    invoking ``cmd.exe``; on POSIX, list args are exec'd directly.
+    """
+    argv: tuple[str, ...]
+    use_shell: bool
+    if isinstance(args, str):
+        if is_windows():
+            # The user gave us a string; pass it to cmd.exe explicitly
+            # so we don't depend on the default shell being sh.
+            argv = ("cmd.exe", "/c", args)
+            use_shell = False
+        else:
+            argv = (args,)
+            use_shell = True
+    else:
+        argv = tuple(args)
+        use_shell = False
+
+    merged_env: dict[str, str] | None = None
+    if env is not None:
+        merged_env = os.environ.copy()
+        merged_env.update({k: v for k, v in env.items() if v is not None})
+
+    completed = subprocess.run(
+        list(argv),
+        cwd=str(cwd) if cwd is not None else None,
+        env=merged_env,
+        input=input,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=check,
+        shell=use_shell,
+    )
+    return ShellResult(
+        returncode=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+        command=argv,
+    )
+
+
+async def run_capture(
+    args: Sequence[str] | str,
+    *,
+    cwd: Path | str | None = None,
+    env: dict[str, str] | None = None,
+    timeout: float | None = None,
+    input: str | bytes | None = None,
+) -> ShellResult:
+    """Async wrapper around :func:`run`."""
+    argv: tuple[str, ...]
+    if isinstance(args, str):
+        argv = ("cmd.exe", "/c", args) if is_windows() else (args,)
+    else:
+        argv = tuple(args)
+
+    merged_env: dict[str, str] | None = None
+    if env is not None:
+        merged_env = os.environ.copy()
+        merged_env.update({k: v for k, v in env.items() if v is not None})
+
+    process = await asyncio.create_subprocess_exec(
+        *argv,
+        cwd=str(cwd) if cwd is not None else None,
+        env=merged_env,
+        stdin=asyncio.subprocess.PIPE if input is not None else None,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        if input is None:
+            stdout_b, stderr_b = await process.communicate()
+        else:
+            stdin_data = input.encode("utf-8") if isinstance(input, str) else input
+            stdout_b, stderr_b = await process.communicate(stdin_data)
+    except TimeoutError as exc:
+        process.kill()
+        raise TimeoutError(f"subprocess timed out after {timeout}s") from exc
+    return ShellResult(
+        returncode=process.returncode or 0,
+        stdout=stdout_b.decode("utf-8", errors="replace"),
+        stderr=stderr_b.decode("utf-8", errors="replace"),
+        command=argv,
+    )
+
+
+def which(executable: str) -> str | None:
+    """Return the absolute path of ``executable`` or None.
+
+    Thin wrapper around :func:`shutil.which` that swallows the
+    ``PATHEXT`` quirks on Windows (shutil already handles those).
+    """
+    import shutil
+
+    return shutil.which(executable)
+
+
+# Silence unused-import warnings for symbols only used in some branches.
+_ = Any

forgecli/platform/update.py

@@ -0,0 +1,252 @@
+"""Update check + version reporting.
+
+ForgeCLI queries the public PyPI JSON API for the latest release
+of the project and surfaces a friendly "update available" notice.
+
+The check is:
+
+* **Off by default.** The CLI never hits the network unless the
+  user runs ``forge --check-update`` or sets
+  ``FORGECLI_CHECK_UPDATE=1``.
+* **Cached.** The latest version is cached in
+  ``$config_dir/update.json`` for ``FORGECLI_UPDATE_CACHE_TTL``
+  seconds (default 24h).
+* **Quiet on failure.** Network errors return ``None`` and are
+  swallowed; the CLI should still launch when offline.
+* **Configurable.** ``FORGECLI_PYPI_URL`` overrides the registry
+  base URL (useful for staging builds and tests).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Final
+
+import httpx
+
+from forgecli import __version__ as _current_version
+from forgecli.platform.core import getenv
+from forgecli.platform.paths import data_dir, ensure_directory
+
+DEFAULT_PYPI_URL: Final[str] = "https://pypi.org/pypi/forgecli/json"
+DEFAULT_TTL_SECONDS: Final[int] = 86_400  # 24h
+HTTP_TIMEOUT_SECONDS: Final[float] = 5.0
+CACHE_FILENAME: Final[str] = "update.json"
+
+
+@dataclass(frozen=True)
+class UpdateInfo:
+    """The result of a version check."""
+
+    current: str
+    latest: str | None
+    update_available: bool
+    checked_at: datetime
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "current": self.current,
+            "latest": self.latest,
+            "update_available": self.update_available,
+            "checked_at": self.checked_at.isoformat(),
+            "error": self.error,
+        }
+
+
+def current_version() -> str:
+    """Return the running ForgeCLI version string."""
+    return _current_version
+
+
+def _cache_path() -> Path:
+    """Return the path to the update cache file."""
+    directory = data_dir()
+    ensure_directory(directory)
+    return directory / CACHE_FILENAME
+
+
+def _read_cache(*, ignore_expiry: bool = False) -> dict[str, object] | None:
+    """Return the cached update payload, or None if missing/expired."""
+    path = _cache_path()
+    if not path.exists():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    checked_at = payload.get("checked_at")
+    if not isinstance(checked_at, (int, float)):
+        return None
+    if not ignore_expiry and (time.time() - float(checked_at)) > _cache_ttl():
+        return None
+    return payload
+
+
+def _write_cache(latest: str) -> None:
+    """Write the latest version to the cache file."""
+    with contextlib.suppress(OSError):
+        _cache_path().write_text(
+            json.dumps(
+                {
+                    "checked_at": time.time(),
+                    "latest": latest,
+                }
+            ),
+            encoding="utf-8",
+        )
+
+
+def _cache_ttl() -> int:
+    raw = getenv("FORGECLI_UPDATE_CACHE_TTL")
+    if raw is None:
+        return DEFAULT_TTL_SECONDS
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return DEFAULT_TTL_SECONDS
+
+
+def _pypi_url() -> str:
+    return getenv("FORGECLI_PYPI_URL") or DEFAULT_PYPI_URL
+
+
+def _parse_version(payload: dict[str, object]) -> str | None:
+    """Pull the latest version string out of a PyPI JSON payload."""
+    info = payload.get("info")
+    if not isinstance(info, dict):
+        return None
+    version = info.get("version")
+    return version if isinstance(version, str) else None
+
+
+def check_for_update(
+    *,
+    force: bool = False,
+    client_factory=None,
+) -> UpdateInfo:
+    """Return an :class:`UpdateInfo` for the current host.
+
+    Reads the cache first; if the cache is fresh, returns its
+    contents. Otherwise queries PyPI and updates the cache.
+    """
+    if not force:
+        cached = _read_cache()
+        if cached is not None:
+            latest = cached.get("latest")
+            if isinstance(latest, str):
+                return _build_info(latest)
+
+    factory = client_factory or _default_client
+    try:
+        with factory() as client:
+            response = client.get(_pypi_url())
+            response.raise_for_status()
+            payload = response.json()
+    except Exception as exc:
+        cached = _read_cache(ignore_expiry=True)
+        if cached is not None:
+            latest = cached.get("latest")
+            if isinstance(latest, str):
+                return UpdateInfo(
+                    current=current_version(),
+                    latest=latest,
+                    update_available=_is_newer(latest, current_version()),
+                    checked_at=datetime.now(UTC),
+                    error=f"Offline fallback (error: {exc!r})",
+                )
+        return UpdateInfo(
+            current=current_version(),
+            latest=None,
+            update_available=False,
+            checked_at=datetime.now(UTC),
+            error=repr(exc),
+        )
+
+    latest = _parse_version(payload) if isinstance(payload, dict) else None
+    if latest is not None:
+        _write_cache(latest)
+    return _build_info(latest)
+
+
+def _build_info(latest: str | None) -> UpdateInfo:
+    """Return an :class:`UpdateInfo` for ``latest`` (may be None)."""
+    current = current_version()
+    update_available = latest is not None and _is_newer(latest, current)
+    return UpdateInfo(
+        current=current,
+        latest=latest,
+        update_available=update_available,
+        checked_at=datetime.now(UTC),
+    )
+
+
+def _is_newer(latest: str, current: str) -> bool:
+    """Return True when ``latest`` is a newer version than ``current``.
+
+    Uses a simple tuple comparison on dotted-version segments. We
+    don't try to handle pre-releases / post-releases specially —
+    those are advisory at best and "newer" is what the user usually
+    wants to see.
+    """
+    def _parts(version: str) -> tuple[int, ...]:
+        out: list[int] = []
+        for chunk in version.split("."):
+            digits = ""
+            for ch in chunk:
+                if ch.isdigit():
+                    digits += ch
+                else:
+                    break
+            if digits:
+                out.append(int(digits))
+            else:
+                out.append(0)
+        return tuple(out)
+
+    return _parts(latest) > _parts(current)
+
+
+def _default_client():
+    """Return a default :class:`httpx.Client`.
+
+    Honors the ``FORGECLI_NO_PROXY`` and ``HTTP_PROXY`` env vars;
+    sets a short timeout so the check never blocks the CLI.
+    """
+    trust_env = bool(getenv("FORGECLI_TRUST_ENV"))
+    return httpx.Client(timeout=HTTP_TIMEOUT_SECONDS, trust_env=trust_env)
+
+
+# ---------------------------------------------------------------------------
+# Public utilities
+# ---------------------------------------------------------------------------
+
+
+def should_check_on_startup() -> bool:
+    """Return True if the CLI should check for updates at startup."""
+    if getenv("FORGECLI_NO_UPDATE_CHECK") == "1":
+        return False
+    return getenv("FORGECLI_CHECK_UPDATE") == "1"
+
+
+def upgrade_command() -> str:
+    """Return the platform-appropriate upgrade command line."""
+    return "uv tool upgrade forgecli   (or:  pip install --upgrade forgecli)"
+
+
+__all__ = [
+    "DEFAULT_PYPI_URL",
+    "DEFAULT_TTL_SECONDS",
+    "UpdateInfo",
+    "check_for_update",
+    "current_version",
+    "should_check_on_startup",
+    "upgrade_command",
+]