multi-forge 0.2.0__py3-none-any.whl

forge/core/ops/proxy.py

@@ -0,0 +1,146 @@
+"""Shared proxy operations (command-core).
+
+These operations are UI-agnostic and can be invoked from both:
+
+- the CLI (`forge proxy ...`), and
+- the in-chat direct command dispatcher (`%proxy ...`).
+
+They return structured data and raise typed exceptions on failure.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from forge.config.loader import load_proxy_instance_config
+from forge.config.schema import ProxyInstanceConfig
+from forge.proxy.proxies import (
+    ProxyEntry,
+    ProxyRegistryCorruptedError,
+    ProxyRegistryStore,
+)
+
+from .context import ExecutionContext
+from .session import ForgeOpError
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ListProxiesItem:
+    proxy_id: str
+    entry: ProxyEntry
+    config: ProxyInstanceConfig | None  # None if proxy.yaml missing/corrupt
+
+
+@dataclass(frozen=True)
+class ListProxiesResult:
+    proxies: list[ListProxiesItem]
+
+
+@dataclass(frozen=True)
+class ShowProxyResult:
+    proxy_id: str
+    entry: ProxyEntry | None  # None if proxy has config file but no registry entry
+    config: ProxyInstanceConfig | None
+    config_yaml: str | None  # Raw YAML content for display
+
+
+def list_proxies(*, ctx: ExecutionContext) -> ListProxiesResult:
+    """List all registered proxies with their configurations.
+
+    This is a global operation (lists from ~/.forge/proxies/index.json).
+    The ctx is accepted for API consistency.
+
+    Args:
+        ctx: execution context (unused, for API consistency).
+
+    Returns:
+        ListProxiesResult with proxy entries and configs.
+
+    Raises:
+        ForgeOpError: if the proxy registry cannot be read.
+    """
+    _log.debug("list_proxies: cwd=%s", ctx.cwd)
+
+    store = ProxyRegistryStore()
+
+    try:
+        registry = store.read()
+    except ProxyRegistryCorruptedError as e:
+        raise ForgeOpError(f"Proxy registry error: {e}") from e
+
+    items: list[ListProxiesItem] = []
+    for proxy_id, entry in registry.proxies.items():
+        # Best-effort config load
+        config: ProxyInstanceConfig | None = None
+        try:
+            config = load_proxy_instance_config(proxy_id)
+        except Exception as e:
+            _log.debug("Failed to load config for proxy %r: %s", proxy_id, e)
+
+        items.append(ListProxiesItem(proxy_id=proxy_id, entry=entry, config=config))
+
+    # Sort by proxy_id for consistent output
+    items.sort(key=lambda x: x.proxy_id)
+
+    return ListProxiesResult(proxies=items)
+
+
+def show_proxy(*, ctx: ExecutionContext, proxy_id: str) -> ShowProxyResult:
+    """Show details for a specific proxy.
+
+    The proxy must have either a registry entry or a config file (or both).
+    Registry info (status, PID) is best-effort enrichment.
+
+    Args:
+        ctx: execution context (unused, for API consistency).
+        proxy_id: the proxy ID to show.
+
+    Returns:
+        ShowProxyResult with entry, config, and raw YAML.
+
+    Raises:
+        ForgeOpError: if the proxy is not found in both registry and filesystem.
+    """
+    _log.debug("show_proxy: proxy_id=%s", proxy_id)
+
+    # Best-effort registry lookup
+    entry: ProxyEntry | None = None
+    store = ProxyRegistryStore()
+    try:
+        registry = store.read()
+        entry = registry.proxies.get(proxy_id)
+    except ProxyRegistryCorruptedError:
+        _log.debug("Registry unreadable, proceeding without registry info")
+
+    # Load config
+    config: ProxyInstanceConfig | None = None
+    config_yaml: str | None = None
+
+    try:
+        config = load_proxy_instance_config(proxy_id)
+    except Exception as e:
+        _log.debug("Failed to load config for proxy %r: %s", proxy_id, e)
+
+    # Load raw YAML for display
+    from forge.config.loader import get_proxy_file_path
+
+    proxy_path = get_proxy_file_path(proxy_id)
+    if proxy_path.exists():
+        try:
+            config_yaml = proxy_path.read_text()
+        except Exception as e:
+            _log.debug("Failed to read proxy file %s: %s", proxy_path, e)
+
+    # Must have at least one source of truth
+    if entry is None and config_yaml is None:
+        raise ForgeOpError(f"Proxy '{proxy_id}' not found")
+
+    return ShowProxyResult(
+        proxy_id=proxy_id,
+        entry=entry,
+        config=config,
+        config_yaml=config_yaml,
+    )

forge/core/ops/resolution.py

@@ -0,0 +1,135 @@
+"""Repo-wide session resolution.
+
+Shared two-tier resolver used by session CLI commands and guard CLI.
+Resolves a named session with current-project preference, falling back
+to a repo-scoped scan when the session lives in a sibling forge_root.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from forge.session import SessionIndexEntry, SessionManager, SessionState, SessionStore
+from forge.session.exceptions import (
+    AmbiguousSessionError,
+    ForgeSessionError,
+    SessionNotFoundError,
+)
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ResolvedSession:
+    """Result of repo-wide session resolution."""
+
+    name: str
+    entry: SessionIndexEntry
+    store: SessionStore
+    state: SessionState
+    forge_root: str
+    is_cross_project: bool
+
+
+def resolve_session_repo_wide(
+    name: str,
+    cwd_forge_root: str | None,
+    *,
+    manager: SessionManager | None = None,
+) -> ResolvedSession:
+    """Resolve a named session with repo-wide scope and current-project preference.
+
+    Two-tier resolution (no global fast path to prevent cross-repo jumps):
+
+    1. Tier 1: Try cwd_forge_root (O(1) compound-key index lookup).
+    2. Tier 2: Repo-scoped scan (project_root_filter) for cross-worktree matches.
+
+    Tiebreaker: if multiple matches in the same repo, prefer cwd_forge_root.
+
+    Raises:
+        SessionNotFoundError: session not found anywhere in the repo.
+        AmbiguousSessionError: multiple matches, none in cwd_forge_root.
+    """
+    if manager is None:
+        manager = SessionManager()
+
+    # Tier 1: same project (O(1) index lookup)
+    if cwd_forge_root is not None:
+        try:
+            entry = manager.get_session_entry(name, forge_root=cwd_forge_root)
+            store = SessionStore(entry.root, name)
+            return ResolvedSession(
+                name=name,
+                entry=entry,
+                store=store,
+                state=store.read(),
+                forge_root=entry.root,
+                is_cross_project=False,
+            )
+        except (ForgeSessionError, FileNotFoundError):
+            pass
+
+    # Tier 2: repo-scoped scan (cross-worktree)
+    project_root = _derive_project_root(cwd_forge_root, manager)
+    if project_root is None:
+        raise SessionNotFoundError(name)
+
+    siblings = manager.list_sessions(project_root_filter=project_root)
+    matches = [(n, e) for n, e in siblings if n == name]
+
+    if not matches:
+        raise SessionNotFoundError(name)
+
+    if len(matches) == 1:
+        e = matches[0][1]
+        store = SessionStore(e.root, name)
+        return ResolvedSession(
+            name=name,
+            entry=e,
+            store=store,
+            state=store.read(),
+            forge_root=e.root,
+            is_cross_project=e.root != cwd_forge_root,
+        )
+
+    # Multiple matches: prefer current forge_root as tiebreaker
+    if cwd_forge_root is not None:
+        for _, e in matches:
+            if e.root == cwd_forge_root:
+                store = SessionStore(e.root, name)
+                return ResolvedSession(
+                    name=name, entry=e, store=store, state=store.read(), forge_root=e.root, is_cross_project=False
+                )
+
+    roots = [e.root for _, e in matches]
+    raise AmbiguousSessionError(name, roots)
+
+
+def _derive_project_root(cwd_forge_root: str | None, manager: SessionManager) -> str | None:
+    """Derive the logical repo root for Tier 2 scanning.
+
+    Uses manager.resolve_project_root first (git subprocess), then falls
+    back to ExecutionContext path walking (handles fake .git dirs in tests
+    and directories that aren't real git worktrees).
+    """
+    if cwd_forge_root is not None:
+        try:
+            pr = manager.resolve_project_root(cwd_forge_root)
+            # resolve_project_root falls back to returning the input path
+            # when git fails. That's not useful for repo-scoped filtering,
+            # so fall through to CWD-based derivation.
+            if pr != str(Path(cwd_forge_root).resolve()):
+                return pr
+        except Exception:
+            pass
+
+    try:
+        from forge.core.ops.context import ExecutionContext
+
+        ctx = ExecutionContext.from_cwd()
+        return str(ctx.project_root)
+    except Exception:
+        _log.debug("Could not derive project_root from CWD or forge_root=%s", cwd_forge_root)
+        return None

forge/core/ops/session.py

@@ -0,0 +1,344 @@
+"""Shared session operations (command-core).
+
+These operations are UI-agnostic and can be invoked from both:
+
+- the CLI (`forge session ...`), and
+- the in-chat direct command dispatcher (`%session ...`).
+
+They return structured data and raise typed exceptions on failure.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from forge.session import (
+    ForgeSessionError,
+    SessionIndexEntry,
+    SessionManager,
+    SessionState,
+    SessionStore,
+    clear_overrides,
+    compute_effective_intent,
+    delete_override,
+    set_override,
+)
+from forge.session.exceptions import (
+    InvalidOverrideKeyError,
+    InvalidOverrideValueError,
+)
+from forge.session.overrides import parse_value, validate_key
+
+from .context import ExecutionContext
+
+_log = logging.getLogger(__name__)
+
+
+class ForgeOpError(RuntimeError):
+    """Raised when a command-core operation fails."""
+
+
+@dataclass(frozen=True)
+class ListSessionsItem:
+    name: str
+    entry: SessionIndexEntry
+    proxy_template: str | None
+    is_active: bool
+
+
+@dataclass(frozen=True)
+class ListSessionsResult:
+    sessions: list[ListSessionsItem]
+
+
+VALID_SCOPES = {"repo", "project", "all"}
+
+
+def _scope_filters(ctx: ExecutionContext, scope: str) -> tuple[str | None, str | None]:
+    """Compute (project_root_filter, forge_root_filter) for a given scope.
+
+    Shared by list_sessions() and list_sessions_older_than() to ensure
+    identical fallback behavior.
+    """
+    if scope == "repo":
+        return str(ctx.project_root), None
+    if scope == "project":
+        if ctx.forge_root is not None:
+            return None, str(ctx.forge_root)
+        _log.debug("No forge_root for --scope project, falling back to repo scope")
+        return str(ctx.project_root), None
+    # scope == "all"
+    return None, None
+
+
+def list_sessions(*, ctx: ExecutionContext, include_incognito: bool, scope: str = "repo") -> ListSessionsResult:
+    """List sessions with lightweight derived metadata.
+
+    Args:
+        ctx: execution context (provides project_root and forge_root for filtering).
+        include_incognito: whether to include incognito sessions.
+        scope: filtering scope:
+            - ``"repo"``: sessions in the same logical repo (project_root match). Default.
+            - ``"project"``: sessions in the same Forge project (forge_root match).
+            - ``"all"``: no filtering (global).
+
+    Returns:
+        ListSessionsResult.
+
+    Raises:
+        ForgeOpError: if the session subsystem fails or scope is invalid.
+    """
+    if scope not in VALID_SCOPES:
+        raise ForgeOpError(f"Invalid scope: {scope!r}. Must be one of {VALID_SCOPES}")
+
+    _log.debug(
+        "list_sessions: cwd=%s, project_root=%s, forge_root=%s, scope=%s",
+        ctx.cwd,
+        ctx.project_root,
+        ctx.forge_root,
+        scope,
+    )
+
+    manager = SessionManager()
+    project_root_filter, forge_root_filter = _scope_filters(ctx, scope)
+
+    try:
+        sessions = manager.list_sessions(
+            include_incognito=include_incognito,
+            project_root_filter=project_root_filter,
+            forge_root_filter=forge_root_filter,
+        )
+    except ForgeSessionError as e:
+        raise ForgeOpError(str(e)) from e
+
+    items: list[ListSessionsItem] = []
+    for name, entry in sessions:
+        proxy_template: str | None = None
+
+        try:
+            manifest = manager.get_session(name, forge_root=entry.forge_root or entry.worktree_path)
+            if manifest.intent.proxy:
+                proxy_template = manifest.intent.proxy.template
+            else:
+                proxy_template = "direct"
+        except ForgeSessionError as e:
+            # Best-effort: listing should not fail if a manifest is missing/corrupt.
+            _log.debug("Failed to read manifest for session %r: %s", name, e)
+
+        items.append(
+            ListSessionsItem(
+                name=name,
+                entry=entry,
+                proxy_template=proxy_template,
+                is_active=False,
+            )
+        )
+
+    return ListSessionsResult(sessions=items)
+
+
+def list_sessions_older_than(
+    *,
+    older_than_days: int,
+    include_incognito: bool = True,
+    project_root_filter: str | None = None,
+    forge_root_filter: str | None = None,
+) -> list[tuple[str, SessionIndexEntry]]:
+    """List sessions whose last_accessed_at is older than the threshold.
+
+    Entries with unparseable timestamps are excluded (they cannot be confirmed
+    as old). This is a shared op used by both CLI and %session list.
+    Respects the same scope filters as list_sessions().
+    """
+    from datetime import UTC, datetime
+
+    from forge.core.state import parse_iso
+
+    manager = SessionManager()
+    all_sessions = manager.list_sessions(
+        include_incognito=include_incognito,
+        project_root_filter=project_root_filter,
+        forge_root_filter=forge_root_filter,
+    )
+
+    result: list[tuple[str, SessionIndexEntry]] = []
+    for name, entry in all_sessions:
+        try:
+            dt = parse_iso(entry.last_accessed_at)
+            age_days = (datetime.now(UTC) - dt).total_seconds() / 86400
+        except (ValueError, TypeError, AttributeError):
+            continue
+        if age_days > older_than_days:
+            result.append((name, entry))
+    return result
+
+
+# --- Session resolution ---
+
+
+@dataclass(frozen=True)
+class ResolveSessionResult:
+    """Result of resolving a session by name or CWD."""
+
+    store: SessionStore
+    state: SessionState
+
+
+def resolve_session(*, ctx: ExecutionContext, session_name: str | None = None) -> ResolveSessionResult:
+    """Resolve a session by explicit name or current session from CWD.
+
+    Named sessions use repo-wide two-tier resolution (current forge_root
+    preference, then repo-scoped scan). Unnamed falls back to $FORGE_SESSION.
+
+    Args:
+        ctx: execution context (provides forge_root for scoped resolution).
+        session_name: explicit session name. If None, resolves current session.
+
+    Returns:
+        ResolveSessionResult with store and state.
+
+    Raises:
+        ForgeOpError: if no active session or session not found.
+    """
+    manager = SessionManager()
+
+    try:
+        if session_name:
+            from forge.core.ops.resolution import resolve_session_repo_wide
+
+            cwd_fr = str(ctx.forge_root) if ctx.forge_root else None
+            resolved = resolve_session_repo_wide(session_name, cwd_fr, manager=manager)
+            return ResolveSessionResult(store=resolved.store, state=resolved.state)
+        else:
+            env_name = os.environ.get("FORGE_SESSION")
+            if env_name:
+                store = manager.get_session_store(env_name)
+                state = store.read()
+            else:
+                raise ForgeOpError("No session specified. Use --session or set $FORGE_SESSION.")
+    except ForgeSessionError as e:
+        raise ForgeOpError(str(e)) from e
+
+    return ResolveSessionResult(store=store, state=state)
+
+
+# --- Session override mutations ---
+
+
+@dataclass(frozen=True)
+class SetOverrideResult:
+    """Result of setting a session override."""
+
+    key: str
+    value: Any
+
+
+def set_session_override(
+    *,
+    ctx: ExecutionContext,
+    session_name: str | None = None,
+    key: str,
+    value_str: str,
+) -> SetOverrideResult:
+    """Validate, apply, and persist a session override.
+
+    Args:
+        ctx: execution context.
+        session_name: explicit session name. If None, resolves current session.
+        key: dot-notation override key (e.g., "agent", "proxy.template").
+        value_str: string value (parsed as JSON first, then as string).
+
+    Returns:
+        SetOverrideResult with key and parsed value.
+
+    Raises:
+        ForgeOpError: on invalid key, invalid value, validation failure, or IO error.
+    """
+    resolved = resolve_session(ctx=ctx, session_name=session_name)
+    store = resolved.store
+
+    try:
+        # Validate key before acquiring lock (wildcards handled by set_override)
+        if "*" not in key:
+            validate_key(key)
+
+        parsed_value = parse_value(value_str)
+
+        # Apply + validate + persist atomically under lock.
+        # The mutate callback receives the fresh state from disk, avoiding TOCTOU.
+        def _mutate(m: SessionState) -> None:
+            set_override(m.overrides, key, parsed_value)
+            compute_effective_intent(m, strict=True, override_key=key)
+
+        store.update(timeout_s=5.0, mutate=_mutate)
+
+        return SetOverrideResult(key=key, value=parsed_value)
+
+    except (InvalidOverrideKeyError, InvalidOverrideValueError) as e:
+        raise ForgeOpError(str(e)) from e
+    except ForgeSessionError as e:
+        raise ForgeOpError(str(e)) from e
+
+
+@dataclass(frozen=True)
+class ResetOverridesResult:
+    """Result of resetting session overrides."""
+
+    cleared_all: bool
+    key: str | None  # None if cleared all
+    was_present: bool  # whether the key had an override (or overrides existed)
+
+
+def reset_session_overrides(
+    *,
+    ctx: ExecutionContext,
+    session_name: str | None = None,
+    key: str | None = None,
+) -> ResetOverridesResult:
+    """Delete a single override or clear all overrides.
+
+    Args:
+        ctx: execution context.
+        session_name: explicit session name. If None, resolves current session.
+        key: override key to delete. If None, clears all overrides.
+
+    Returns:
+        ResetOverridesResult.
+
+    Raises:
+        ForgeOpError: on invalid key or IO error.
+    """
+    resolved = resolve_session(ctx=ctx, session_name=session_name)
+    store = resolved.store
+
+    try:
+        if key:
+            # Mutate under lock: delete_override on fresh state
+            result_holder: dict[str, Any] = {}
+
+            def _mutate_delete(m: SessionState) -> None:
+                result_holder["deleted"] = delete_override(m.overrides, key)
+
+            store.update(timeout_s=5.0, mutate=_mutate_delete)
+            return ResetOverridesResult(
+                cleared_all=False,
+                key=key,
+                was_present=result_holder.get("deleted", False),
+            )
+        else:
+            # Peek at current state to report whether overrides existed
+            had_overrides = bool(resolved.state.overrides)
+            if had_overrides:
+                store.update(
+                    timeout_s=5.0,
+                    mutate=lambda m: clear_overrides(m.overrides),
+                )
+            return ResetOverridesResult(cleared_all=True, key=None, was_present=had_overrides)
+
+    except InvalidOverrideKeyError as e:
+        raise ForgeOpError(str(e)) from e
+    except ForgeSessionError as e:
+        raise ForgeOpError(str(e)) from e