forgex-cli 0.1.0__py3-none-any.whl

forgex/cli/session.py

@@ -0,0 +1,95 @@
+"""Interactive session state management for FORGEX REPL."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+
+from forgex.cli.context_memory import ConversationContext
+from forgex.cli.ui import UI, Output
+from forgex.config import ForgexConfig, load_config
+from forgex.config.loader import load_env_files
+from forgex.orchestration.state import StateStore, TaskStore
+from forgex.project import ProjectDetection, detect_project
+from forgex.schemas.project import ProjectState
+from forgex.schemas.task import Task
+from forgex.utils.paths import find_project_root
+
+
+@dataclass
+class Session:
+    """Encapsulates persistent state during an interactive FORGEX terminal session."""
+
+    project_root: Path | None = None
+    config: ForgexConfig = field(default_factory=ForgexConfig)
+    ui: UI = field(default_factory=lambda: UI(mode=Output.RICH))
+    console: Console = field(default_factory=Console)
+    history: list[str] = field(default_factory=list)
+    context: ConversationContext = field(default_factory=ConversationContext)
+    _router: Any = None
+
+    def __post_init__(self) -> None:
+        self.refresh()
+
+    def refresh(self) -> None:
+        """Refresh project root, environment, and configuration from disk."""
+        self.project_root = find_project_root()
+        load_env_files(self.project_root)
+        self.config = load_config(self.project_root)
+        self._router = None
+
+    @property
+    def is_attached(self) -> bool:
+        """True if the session is currently attached to an initialized project."""
+        return self.project_root is not None and (self.project_root / ".forgex").is_dir()
+
+    @property
+    def project_name(self) -> str:
+        """Name of the attached project directory, or 'unattached'."""
+        if self.project_root is not None:
+            return self.project_root.name
+        return "unattached"
+
+    def detect(self) -> ProjectDetection | None:
+        """Run project detector on current directory or attached project."""
+        target = self.project_root or Path.cwd()
+        return detect_project(target)
+
+    def get_state(self) -> ProjectState | None:
+        """Load current ProjectState if attached."""
+        if not self.is_attached or self.project_root is None:
+            return None
+        try:
+            return StateStore(self.project_root).load()
+        except Exception:
+            return None
+
+    def get_tasks(self) -> list[Task]:
+        """Load project tasks if attached."""
+        if not self.is_attached or self.project_root is None:
+            return []
+        try:
+            return TaskStore(self.project_root).load()
+        except Exception:
+            return []
+
+    def get_router(self) -> Any:
+        """Lazily instantiate and return the ModelRouter."""
+        if self._router is None:
+            from forgex.models.router import ModelRouter
+
+            self._router = ModelRouter(self.config)
+        return self._router
+
+    def change_directory(self, target: Path | str) -> bool:
+        """Change working directory and refresh session."""
+        dest = Path(target).expanduser().resolve()
+        if not dest.is_dir():
+            return False
+        os.chdir(dest)
+        self.refresh()
+        return True

forgex/cli/ui.py

@@ -0,0 +1,113 @@
+"""Terminal output adapter (spec section 23).
+
+All user-facing output goes through :class:`UI` so the modes required by
+spec section 23 (``--plain`` / ``--json`` / ``--quiet``) behave
+consistently across every command.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from enum import Enum
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.prompt import Confirm
+from rich.theme import Theme
+
+_THEME = Theme(
+    {
+        "forgex.title": "bold cyan",
+        "forgex.ok": "green",
+        "forgex.warn": "yellow",
+        "forgex.err": "red",
+        "forgex.muted": "dim",
+    }
+)
+
+
+class Output(str, Enum):
+    RICH = "rich"
+    PLAIN = "plain"
+    JSON = "json"
+    QUIET = "quiet"
+
+
+JsonFlag = Annotated[bool, typer.Option("--json", help="Machine-readable JSON output.")]
+PlainFlag = Annotated[bool, typer.Option("--plain", help="Plain output (CI/SSH safe).")]
+
+
+class UI:
+    def __init__(self, mode: Output, console: Console | None = None) -> None:
+        self.mode = mode
+        if console is not None:
+            self.console = console
+        elif mode is Output.JSON:
+            self.console = Console(theme=_THEME, soft_wrap=True, highlight=False)
+        else:
+            self.console = Console(theme=_THEME)
+
+    def ok(self, message: str) -> None:
+        if self.mode is Output.QUIET or self.mode is Output.JSON:
+            return
+        if self.mode is Output.RICH:
+            self.console.print(f"[green]✓[/green] {message}")
+        else:
+            self.console.print(f"OK: {message}")
+
+    def warn(self, message: str) -> None:
+        if self.mode is Output.QUIET or self.mode is Output.JSON:
+            return
+        if self.mode is Output.RICH:
+            self.console.print(f"[yellow]![/yellow] {message}")
+        else:
+            self.console.print(f"WARN: {message}")
+
+    def error(self, message: str) -> None:
+        if self.mode is Output.JSON:
+            return
+        if self.mode is Output.RICH:
+            self.console.print(f"[red]✗[/red] {message}")
+        else:
+            self.console.print(f"ERROR: {message}")
+
+    def text(self, message: str) -> None:
+        if self.mode is Output.QUIET or self.mode is Output.JSON:
+            return
+        self.console.print(message)
+
+    def data(self, payload: dict[str, Any]) -> None:
+        if self.mode is Output.JSON:
+            self.console.print(json.dumps(payload, indent=2, default=str), soft_wrap=True, highlight=False)
+
+
+def ui_from(
+    ctx: typer.Context,
+    *,
+    json_out: bool = False,
+    plain: bool = False,
+) -> UI:
+    obj = ctx.obj or {}
+    if json_out or obj.get("json"):
+        mode = Output.JSON
+    elif plain or obj.get("plain"):
+        mode = Output.PLAIN
+    elif obj.get("quiet"):
+        mode = Output.QUIET
+    else:
+        mode = Output.RICH
+
+    return UI(mode=mode)
+
+
+def make_approval(ui: UI):
+    """Interactive approval callback (spec section 33)."""
+
+    def approve(description: str) -> bool:
+        if ui.mode is not Output.RICH or not sys.stdin.isatty():
+            return False
+        return Confirm.ask(f"FORGEX wants to: {description}\nAllow?", default=False)
+
+    return approve

forgex/config/__init__.py

@@ -0,0 +1,53 @@
+"""Configuration package: layered loading with Pydantic validation."""
+
+from forgex.config.loader import (
+    CONFIG_FILE_NAME,
+    ENV_FILE_NAME,
+    FORGEX_DIR_NAME,
+    global_config_path,
+    load_config,
+    load_env_files,
+    parse_env_file,
+    project_config_path,
+    save_config,
+    set_config_value,
+    store_secret,
+)
+from forgex.config.schema import (
+    AgentModelBinding,
+    EnsembleConfig,
+    FallbackConfig,
+    ForgexConfig,
+    ModelsConfig,
+    PermissionsConfig,
+    ProviderConfig,
+    ResearchConfig,
+    SandboxConfig,
+    TerminalConfig,
+    WorkflowConfig,
+)
+
+__all__ = [
+    "CONFIG_FILE_NAME",
+    "ENV_FILE_NAME",
+    "FORGEX_DIR_NAME",
+    "AgentModelBinding",
+    "EnsembleConfig",
+    "FallbackConfig",
+    "ForgexConfig",
+    "ModelsConfig",
+    "PermissionsConfig",
+    "ProviderConfig",
+    "ResearchConfig",
+    "SandboxConfig",
+    "TerminalConfig",
+    "WorkflowConfig",
+    "global_config_path",
+    "load_config",
+    "load_env_files",
+    "parse_env_file",
+    "project_config_path",
+    "save_config",
+    "set_config_value",
+    "store_secret",
+]

forgex/config/loader.py

@@ -0,0 +1,189 @@
+"""Layered configuration loading, saving, and dotted-key editing."""
+
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+from pydantic import ValidationError
+
+from forgex.config.schema import ForgexConfig
+from forgex.schemas.error import ConfigError
+
+FORGEX_DIR_NAME = ".forgex"
+CONFIG_FILE_NAME = "config.toml"
+ENV_FILE_NAME = ".env"
+
+
+def global_config_path() -> Path:
+    return Path.home() / FORGEX_DIR_NAME / CONFIG_FILE_NAME
+
+
+def project_config_path(project_root: Path) -> Path:
+    return project_root / FORGEX_DIR_NAME / CONFIG_FILE_NAME
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        msg = f"Invalid TOML in {path}: {exc}"
+        raise ConfigError(msg) from exc
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def load_config(
+    project_root: Path | None = None,
+    overrides: dict[str, Any] | None = None,
+) -> ForgexConfig:
+    """Load merged configuration: defaults < global < project < overrides."""
+    data: dict[str, Any] = ForgexConfig().model_dump()
+    data = _deep_merge(data, _read_toml(global_config_path()))
+    if project_root is not None:
+        data = _deep_merge(data, _read_toml(project_config_path(project_root)))
+    if overrides:
+        data = _deep_merge(data, overrides)
+    try:
+        config = ForgexConfig.model_validate(data)
+    except ValidationError as exc:
+        msg = f"Invalid configuration: {exc.error_count()} error(s): {exc}"
+        raise ConfigError(msg) from exc
+
+    if os.environ.get("FORGEX_OFFLINE") == "1":
+        # Offline mode (§73): web research off; local providers still allowed.
+        config.research.enabled = False
+    return config
+
+
+def save_config(config: ForgexConfig, path: Path) -> None:
+    """Write a full config to *path* as TOML (None values omitted — TOML has no null)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = tomli_w.dumps(config.model_dump(mode="json", exclude_none=True))
+    path.write_text(text, encoding="utf-8")
+
+
+def _coerce(raw: Any) -> Any:
+    """Convert a CLI string into bool/int/float/JSON when unambiguous."""
+    if not isinstance(raw, str):
+        return raw
+    if raw.lower() in ("true", "false"):
+        return raw.lower() == "true"
+    if raw and raw[0] in "[{":
+        try:
+            return json.loads(raw)
+        except ValueError:
+            pass
+    for cast in (int, float):
+        try:
+            return cast(raw)
+        except ValueError:
+            pass
+    return raw
+
+
+def set_config_value(path: Path, dotted_key: str, value: Any) -> ForgexConfig:
+    """Set a dotted key in config at path, validate with Pydantic, and save.
+
+    Refuses to write if the resulting configuration would be invalid.
+    """
+    raw_dict = _read_toml(path) if path.is_file() else {}
+    coerced_value = _coerce(value)
+
+    # Insert into nested dict
+    parts = dotted_key.split(".")
+    curr = raw_dict
+    for part in parts[:-1]:
+        if part not in curr or not isinstance(curr[part], dict):
+            curr[part] = {}
+        curr = curr[part]
+    curr[parts[-1]] = coerced_value
+
+    # Merge onto defaults to validate full schema
+    data = ForgexConfig().model_dump()
+    data = _deep_merge(data, raw_dict)
+
+    try:
+        validated = ForgexConfig.model_validate(data)
+    except ValidationError as exc:
+        msg = f"Invalid configuration for {dotted_key}={value}: {exc}"
+        raise ConfigError(msg) from exc
+
+    # Write validated TOML
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Save the minimal raw_dict or full validated config
+    save_config(validated, path)
+    return validated
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    """Minimal .env parser: comments, optional 'export ', KEY=VALUE, quotes."""
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        line = line.removeprefix("export ")
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        if key:
+            values[key] = value
+    return values
+
+
+def load_env_files(project_root: Path | None = None) -> list[Path]:
+    """Load ~/.forgex/.env then <project>/.env into os.environ with setdefault.
+
+    Priority: real environment always wins; project .env beats global .env.
+    """
+    paths = []
+    if project_root is not None:
+        paths.append(Path(project_root) / ENV_FILE_NAME)
+    paths.append(Path.home() / FORGEX_DIR_NAME / ENV_FILE_NAME)
+    loaded: list[Path] = []
+    for path in paths:
+        if not path.is_file():
+            continue
+        try:
+            values = parse_env_file(path)
+        except OSError:
+            continue
+        for key, value in values.items():
+            os.environ.setdefault(key, value)
+        loaded.append(path)
+    return loaded
+
+
+def store_secret(env_var: str, value: str, *, global_dir: Path | None = None) -> Path:
+    """Persist a secret to ~/.forgex/.env (chmod 600). Never into config files."""
+    target = (global_dir or Path.home() / FORGEX_DIR_NAME) / ENV_FILE_NAME
+    target.parent.mkdir(parents=True, exist_ok=True)
+    existing: dict[str, str] = parse_env_file(target) if target.is_file() else {}
+    existing[env_var] = value
+    lines = [f"{key}={val}" for key, val in existing.items()]
+    target.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    if os.name == "posix":
+        try:
+            os.chmod(target, 0o600)
+        except OSError:
+            pass
+    return target

forgex/config/schema.py

@@ -0,0 +1,145 @@
+"""Pydantic models describing FORGEX configuration.
+
+Priority (highest wins), per spec section 27:
+    CLI arguments > environment (secrets) > project .forgex/config.toml
+    > global ~/.forgex/config.toml > schema defaults.
+
+Secrets NEVER live in these files — providers store only the *name* of
+the environment variable holding the key (``api_key_env``).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from forgex.models.capabilities import ModelCapabilities
+
+
+class WorkflowConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    max_iterations: int = Field(default=5, ge=1, le=20)
+
+
+class PermissionsConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["auto", "ask", "safe"] = "ask"
+
+
+class ProviderConfig(BaseModel):
+    """A provider endpoint description. Contains no secrets."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["openai_compatible", "groq", "local"] = "openai_compatible"
+    base_url: str | None = None
+    api_key_env: str | None = None
+    default_model: str | None = None
+    timeout_seconds: float = 60.0
+    max_retries: int = 2
+
+
+class AgentModelBinding(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str = "groq"
+    model: str | None = None
+
+
+class ModelsConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    architect: AgentModelBinding = Field(default_factory=AgentModelBinding)
+    builder: AgentModelBinding = Field(default_factory=AgentModelBinding)
+    expert_coder: AgentModelBinding = Field(default_factory=AgentModelBinding)
+    supervisor: AgentModelBinding = Field(default_factory=AgentModelBinding)
+    capabilities: dict[str, ModelCapabilities] = Field(default_factory=dict)
+
+
+class FallbackConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    providers: list[str] = Field(default_factory=list)
+
+
+class TerminalConfig(BaseModel):
+    """Command execution policy knobs (spec sections 19, 45)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    allowed: list[str] = Field(default_factory=list)
+    denied: list[str] = Field(default_factory=list)
+    timeout_seconds: int = 120
+    max_output_bytes: int = 1_000_000
+
+
+class SandboxConfig(BaseModel):
+    """Docker sandbox (spec section 20). Default: restricted."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    network: bool = False
+    image: str = "python:3.12-slim"
+    cpu_limit: str | None = None
+    memory_limit: str | None = None
+    read_only: bool = True
+    user: str | None = None
+    timeout_seconds: int = 120
+
+
+class ResearchConfig(BaseModel):
+    """Web research toggle (spec sections 8, 73)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = True
+
+
+class EnsembleConfig(BaseModel):
+    """Multi-model ensemble review (spec section 15)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    reviewers: int = Field(default=2, ge=2, le=4)
+    bindings: list[AgentModelBinding] = Field(default_factory=list)
+
+
+def _default_providers() -> dict[str, ProviderConfig]:
+    return {
+        "groq": ProviderConfig(
+            type="groq",
+            base_url="https://api.groq.com/openai/v1",
+            api_key_env="FORGEX_GROQ_API_KEY",
+            default_model="llama-3.3-70b-versatile",
+        ),
+        "openai_compatible": ProviderConfig(
+            type="openai_compatible",
+            base_url="https://api.openai.com/v1",
+            api_key_env="FORGEX_OPENAI_API_KEY",
+            default_model="gpt-4o-mini",
+        ),
+        "local": ProviderConfig(
+            type="local",
+            base_url="http://localhost:11434/v1",
+        ),
+    }
+
+
+class ForgexConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    workflow: WorkflowConfig = Field(default_factory=WorkflowConfig)
+    permissions: PermissionsConfig = Field(default_factory=PermissionsConfig)
+    terminal: TerminalConfig = Field(default_factory=TerminalConfig)
+    sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
+    research: ResearchConfig = Field(default_factory=ResearchConfig)
+    ensemble: EnsembleConfig = Field(default_factory=EnsembleConfig)
+    fallback: FallbackConfig = Field(default_factory=FallbackConfig)
+    models: ModelsConfig = Field(default_factory=ModelsConfig)
+    providers: dict[str, ProviderConfig] = Field(default_factory=_default_providers)

forgex/context/__init__.py

@@ -0,0 +1,6 @@
+"""Context intelligence (spec sections 16, 17)."""
+
+from forgex.context.manager import ContextBundle, ContextManager
+from forgex.context.retriever import ScoredFile, query_terms
+
+__all__ = ["ContextBundle", "ContextManager", "ScoredFile", "query_terms"]