forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/config/writer.py

@@ -0,0 +1,90 @@
+"""TOML writer helper to update ForgeCLI config settings on the fly."""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib  # py3.11+
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore[no-redef,import-not-found]
+
+
+def dump_toml(data: dict[str, Any]) -> str:
+    """Serialize a dictionary to a basic TOML string (handles flat tables and primitive values)."""
+    lines = []
+    # Write top-level key-values first
+    for k, v in sorted(data.items()):
+        if not isinstance(v, dict):
+            if isinstance(v, bool):
+                lines.append(f"{k} = {str(v).lower()}")
+            elif isinstance(v, (int, float)):
+                lines.append(f"{k} = {v}")
+            elif isinstance(v, str):
+                lines.append(f'{k} = "{v}"')
+            elif isinstance(v, list):
+                items = ", ".join(f'"{x}"' if isinstance(x, str) else str(x) for x in v)
+                lines.append(f"{k} = [{items}]")
+
+    # Write tables
+    for section_name, section_val in sorted(data.items()):
+        if isinstance(section_val, dict):
+            lines.append(f"\n[{section_name}]")
+            for k, v in sorted(section_val.items()):
+                if isinstance(v, bool):
+                    lines.append(f"{k} = {str(v).lower()}")
+                elif isinstance(v, (int, float)):
+                    lines.append(f"{k} = {v}")
+                elif isinstance(v, str):
+                    lines.append(f'{k} = "{v}"')
+                elif isinstance(v, list):
+                    items = ", ".join(f'"{x}"' if isinstance(x, str) else str(x) for x in v)
+                    lines.append(f"{k} = [{items}]")
+
+    return "\n".join(lines).strip() + "\n"
+
+
+def update_config(
+    default_provider: str | None = None,
+    default_model: str | None = None,
+    clear_provider: bool = False,
+    clear_model: bool = False,
+) -> Path:
+    """Update defaults in the active forgecli.toml configuration file."""
+    from forgecli.config.loader import ConfigLoader
+
+    loader = ConfigLoader()
+    # Find existing writeable candidate config file
+    candidates = loader._candidate_paths()
+    target_path = None
+    for p in candidates:
+        if p.exists() and p.name != "pyproject.toml":
+            target_path = p
+            break
+
+    if not target_path:
+        target_path = Path("./forgecli.toml")
+
+    data: dict[str, Any] = {}
+    if target_path.exists():
+        with contextlib.suppress(Exception):
+            data = tomllib.loads(target_path.read_text(encoding="utf-8"))
+
+    if "providers" not in data:
+        data["providers"] = {}
+
+    if clear_provider:
+        data["providers"].pop("default", None)
+    elif default_provider is not None:
+        data["providers"]["default"] = default_provider
+
+    if clear_model:
+        data["providers"].pop("default_model", None)
+    elif default_model is not None:
+        data["providers"]["default_model"] = default_model
+
+    content = dump_toml(data)
+    target_path.write_text(content, encoding="utf-8")
+    return target_path

forgecli/core/__init__.py

@@ -0,0 +1,35 @@
+"""Core orchestration primitives: app context, DI container, events."""
+
+from forgecli.core.container import Container
+from forgecli.core.context import AppContext
+from forgecli.core.errors import (
+    ConfigError,
+    ForgeCLIError,
+    GitError,
+    PipelineError,
+    PluginError,
+    ProviderError,
+)
+from forgecli.core.events import Event, EventBus
+from forgecli.core.logging import configure_logging, get_logger
+from forgecli.core.plugins import Plugin, discover_plugins, install_plugins
+from forgecli.core.service import Service
+
+__all__ = [
+    "AppContext",
+    "ConfigError",
+    "Container",
+    "Event",
+    "EventBus",
+    "ForgeCLIError",
+    "GitError",
+    "PipelineError",
+    "Plugin",
+    "PluginError",
+    "ProviderError",
+    "Service",
+    "configure_logging",
+    "discover_plugins",
+    "get_logger",
+    "install_plugins",
+]

forgecli/core/container.py

@@ -0,0 +1,68 @@
+"""Lightweight dependency-injection container."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class Container:
+    """A minimal service container with factory and singleton registrations.
+
+    The container intentionally avoids any global state; an instance is
+    owned by :class:`forgecli.core.context.AppContext` and created per process.
+    """
+
+    def __init__(self) -> None:
+        self._factories: dict[type, Callable[[Container], Any]] = {}
+        self._singletons: dict[type, Any] = {}
+        self._singleton_flags: dict[type, bool] = {}
+
+    def register(
+        self,
+        interface: type[T],
+        factory: Callable[[Container], T],
+        *,
+        singleton: bool = True,
+    ) -> None:
+        """Register a factory for ``interface``.
+
+        When ``singleton`` is True, the first call to :meth:`resolve` will
+        cache the result and return it for all subsequent calls.
+        """
+        self._factories[interface] = factory
+        self._singleton_flags[interface] = singleton
+        if not singleton:
+            self._singletons.pop(interface, None)
+
+    def register_instance(self, interface: type[T], instance: T) -> None:
+        """Bind a pre-constructed instance to ``interface``."""
+        self._factories[interface] = lambda _c: instance
+        self._singletons[interface] = instance
+        self._singleton_flags[interface] = True
+
+    def resolve(self, interface: type[T]) -> T:
+        """Resolve an instance for ``interface``."""
+        if interface in self._singletons:
+            return self._singletons[interface]  # type: ignore[return-value]
+        if interface not in self._factories:
+            raise KeyError(f"No registration for {interface!r}")
+        instance = self._factories[interface](self)
+        if self._is_singleton(interface):
+            self._singletons[interface] = instance
+        return instance  # type: ignore[return-value]
+
+    def _is_singleton(self, interface: type) -> bool:
+        """Return True if ``interface`` was registered as a singleton."""
+        return self._singleton_flags.get(interface, True)
+
+    def has(self, interface: type) -> bool:
+        return interface in self._factories or interface in self._singletons
+
+    def clear(self) -> None:
+        """Drop all registrations and cached singletons."""
+        self._factories.clear()
+        self._singletons.clear()
+        self._singleton_flags.clear()

forgecli/core/context.py

@@ -0,0 +1,54 @@
+"""Application context: shared state object passed across the CLI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from forgecli.core.container import Container
+from forgecli.core.events import EventBus
+from forgecli.utils.paths import ProjectPaths
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from forgecli.config.loader import ConfigLoader
+    from forgecli.config.settings import ForgeSettings
+
+
+@dataclass
+class AppContext:
+    """Shared, mutable context for one CLI invocation.
+
+    The context is created in :mod:`forgecli.cli.main` and explicitly
+    passed to services that need it. It owns the configuration loader,
+    the DI container, the event bus, and resolved filesystem paths.
+    """
+
+    paths: ProjectPaths
+    loader: ConfigLoader
+    settings: ForgeSettings | None = None
+    container: Container = field(default_factory=Container)
+    event_bus: EventBus = field(default_factory=EventBus)
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    def resolve_settings(self, *, force: bool = False) -> ForgeSettings:
+        """Load (or return cached) settings."""
+        if self.settings is None or force:
+            self.settings = self.loader.load(force=force)
+        return self.settings
+
+    def with_overrides(self, **values: Any) -> AppContext:
+        """Return a shallow copy with extra values merged into ``extras``."""
+        new = AppContext(
+            paths=self.paths,
+            loader=self.loader,
+            settings=self.settings,
+            container=self.container,
+            event_bus=self.event_bus,
+            extras={**self.extras, **values},
+        )
+        return new
+
+    @property
+    def cwd(self) -> Path:
+        return self.paths.cwd

forgecli/core/credentials.py

@@ -0,0 +1,114 @@
+"""Secure storage for API keys with OS keychain (keyring) and encrypted fallback."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import getpass
+import hashlib
+import json
+import sys
+import uuid
+from pathlib import Path
+
+import keyring
+from cryptography.fernet import Fernet
+
+from forgecli.utils.paths import ProjectPaths
+
+KEYRING_SERVICE = "forgectx"
+
+
+def _get_credentials_file() -> Path:
+    paths = ProjectPaths.from_env()
+    paths.config_dir.mkdir(parents=True, exist_ok=True)
+    return paths.config_dir / "credentials.json"
+
+
+def _get_encryption_key() -> bytes:
+    try:
+        host_info = f"{uuid.getnode()}:{getpass.getuser()}:{sys.platform}"
+    except Exception:
+        host_info = "fallback-forgectx-key-salt"
+    key_hash = hashlib.sha256(host_info.encode("utf-8")).digest()
+    return base64.urlsafe_b64encode(key_hash)
+
+
+def _read_encrypted_file() -> dict[str, str]:
+    path = _get_credentials_file()
+    if not path.exists():
+        return {}
+    try:
+        raw_data = path.read_bytes()
+        fernet = Fernet(_get_encryption_key())
+        decrypted = fernet.decrypt(raw_data)
+        return json.loads(decrypted.decode("utf-8"))
+    except Exception:
+        return {}
+
+
+def _write_encrypted_file(data: dict[str, str]) -> None:
+    path = _get_credentials_file()
+    fernet = Fernet(_get_encryption_key())
+    encrypted = fernet.encrypt(json.dumps(data).encode("utf-8"))
+    path.write_bytes(encrypted)
+    with contextlib.suppress(OSError):
+        path.chmod(0o600)
+
+
+def get_api_key(provider: str) -> str | None:
+    """Retrieve the API key for a provider."""
+    provider = provider.lower().strip()
+    try:
+        val = keyring.get_password(KEYRING_SERVICE, provider)
+        if val is not None:
+            return val
+    except Exception:
+        pass
+    data = _read_encrypted_file()
+    return data.get(provider)
+
+
+def set_api_key(provider: str, api_key: str) -> None:
+    """Store an API key in the OS keychain, falling back to encrypted disk storage."""
+    provider = provider.lower().strip()
+    api_key = api_key.strip()
+    if not provider or not api_key:
+        raise ValueError("provider and api_key are required")
+    try:
+        keyring.set_password(KEYRING_SERVICE, provider, api_key)
+        return
+    except Exception:
+        data = _read_encrypted_file()
+        data[provider] = api_key
+        _write_encrypted_file(data)
+
+
+def delete_api_key(provider: str) -> None:
+    """Remove a stored API key."""
+    provider = provider.lower().strip()
+    with contextlib.suppress(Exception):
+        keyring.delete_password(KEYRING_SERVICE, provider)
+    data = _read_encrypted_file()
+    if provider in data:
+        del data[provider]
+        _write_encrypted_file(data)
+
+
+def list_stored_providers() -> list[str]:
+    """Return provider names with stored credentials."""
+    providers = set(_read_encrypted_file())
+    for name in (
+        "openai",
+        "anthropic",
+        "google",
+        "openrouter",
+        "groq",
+        "together",
+    ):
+        try:
+            if keyring.get_password(KEYRING_SERVICE, name):
+                providers.add(name)
+        except Exception:
+            continue
+    return sorted(providers)

forgecli/core/errors.py

@@ -0,0 +1,27 @@
+"""Typed exception hierarchy for ForgeCLI."""
+
+from __future__ import annotations
+
+
+class ForgeCLIError(Exception):
+    """Base class for all ForgeCLI-specific errors."""
+
+
+class ConfigError(ForgeCLIError):
+    """Raised when configuration cannot be loaded or validated."""
+
+
+class ProviderError(ForgeCLIError):
+    """Raised on AI provider failures (network, auth, schema)."""
+
+
+class GitError(ForgeCLIError):
+    """Raised on Git-related failures (missing repo, bad ref, etc)."""
+
+
+class PluginError(ForgeCLIError):
+    """Raised on plugin discovery or lifecycle failures."""
+
+
+class PipelineError(ForgeCLIError):
+    """Raised when a builder/review/planner pipeline cannot complete."""

forgecli/core/events.py

@@ -0,0 +1,67 @@
+"""A tiny pub/sub event bus used for decoupled logging and lifecycle hooks."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+Subscriber = Callable[["Event"], "None | Awaitable[None]"]
+
+
+@dataclass(frozen=True)
+class Event:
+    """An immutable event payload."""
+
+    name: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+class EventBus:
+    """Asynchronous-first pub/sub bus.
+
+    Synchronous subscribers are invoked inline; async subscribers are
+    scheduled via :func:`asyncio.create_task`. The bus is intentionally
+    simple: subscribers cannot block the publisher and ordering is
+    best-effort.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[Subscriber]] = {}
+        self._pending_tasks: set[asyncio.Task[Any]] = set()
+
+    def subscribe(self, name: str, callback: Subscriber) -> None:
+        """Register ``callback`` for events named ``name``."""
+        self._subscribers.setdefault(name, []).append(callback)
+
+    def unsubscribe(self, name: str, callback: Subscriber) -> None:
+        bucket = self._subscribers.get(name)
+        if not bucket:
+            return
+        with contextlib.suppress(ValueError):
+            bucket.remove(callback)
+
+    async def publish(self, name: str, **payload: Any) -> None:
+        """Publish an event, dispatching to all registered subscribers."""
+        event = Event(name=name, payload=dict(payload))
+        for callback in list(self._subscribers.get(name, ())):
+            result = callback(event)
+            if asyncio.iscoroutine(result):
+                await result
+
+    def emit(self, name: str, **payload: Any) -> None:
+        """Synchronous variant of :meth:`publish`; async subs are not awaited."""
+        event = Event(name=name, payload=dict(payload))
+        for callback in list(self._subscribers.get(name, ())):
+            result = callback(event)
+            if asyncio.iscoroutine(result):
+                # Fire-and-forget; require an event loop to be running.
+                with contextlib.suppress(RuntimeError):
+                    loop = asyncio.get_running_loop()
+                    task = loop.create_task(result)
+                    self._pending_tasks.add(task)
+                    task.add_done_callback(self._pending_tasks.discard)

forgecli/core/logging.py

@@ -0,0 +1,47 @@
+"""Logging configuration built on the standard library ``logging`` package."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Final
+
+_LOG_FORMAT: Final[str] = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+_configured = False
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """Configure root logging once for the lifetime of the process."""
+    global _configured
+    if _configured:
+        new_level = _coerce_level(level)
+        if logging.getLogger().level != logging.DEBUG or new_level == logging.DEBUG:
+            logging.getLogger().setLevel(new_level)
+        return
+
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(_coerce_level(level))
+
+    # Quiet noisy third-party loggers.
+    for noisy in ("httpx", "httpcore", "git", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+    _configured = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a configured logger, configuring root logging lazily."""
+    if not _configured:
+        configure_logging()
+    return logging.getLogger(name)
+
+
+def _coerce_level(level: str) -> int:
+    if level.isdigit():
+        return int(level)
+    return logging.getLevelName(level.upper())