multi-forge 0.2.0__py3-none-any.whl

forge/cli/backend.py

@@ -0,0 +1,298 @@
+"""Backend management CLI commands.
+
+Provides commands to manage backend services (LiteLLM, etc.) that proxies depend on:
+- forge backend list: List all backends
+- forge backend create: Create backend config
+- forge backend start: Start a backend instance
+- forge backend stop: Stop a backend instance
+- forge backend delete: Delete backend config or instance
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from forge.backend import BackendManager
+from forge.backend.adapters import get_adapter
+from forge.backend.creation import create_backend_config, get_backend_config_path
+from forge.backend.registry import BackendRegistryStore, is_pid_alive
+from forge.core.paths import display_path, get_forge_home
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def backend() -> None:
+    """Manage backends (LiteLLM, etc.).
+
+    \b
+    Examples:
+        forge backend list                     # List backends
+        forge backend create litellm           # Create backend config
+        forge backend start litellm -p 4000    # Start an instance
+    """
+
+
+@backend.command("list")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def list_cmd(as_json: bool) -> None:
+    """List all backends."""
+    console = Console(width=200)
+    store = BackendRegistryStore()
+
+    backends = store.read().backends
+
+    if as_json:
+        import json
+
+        data = []
+        for backend_id, b in backends.items():
+            data.append(
+                {
+                    "backend_id": b.backend_id,
+                    "adapter_type": b.adapter_type,
+                    "port": b.port,
+                    "pid": b.pid,
+                    "status": b.status,
+                }
+            )
+        click.echo(json.dumps(data, indent=2, default=str))
+        return
+
+    if not backends:
+        console.print("No backends found.")
+        console.print("\n[dim]Tip: Run 'forge backend create litellm'.[/dim]")
+        return
+
+    table = Table(title="Forge Backends")
+    table.add_column("BACKEND ID", style="cyan")
+    table.add_column("ADAPTER")
+    table.add_column("PORT", justify="right")
+    table.add_column("PID", justify="right")
+    table.add_column("STATUS")
+
+    for backend_id, backend in backends.items():
+        table.add_row(
+            backend_id,
+            backend.adapter_type,
+            str(backend.port),
+            str(backend.pid) if backend.pid else "-",
+            backend.status,
+        )
+
+    console.print(table)
+
+
+@backend.command("show")
+@click.argument("backend_id")
+@click.option("--raw", is_flag=True, help="Output raw config without syntax highlighting")
+def show_cmd(backend_id: str, raw: bool) -> None:
+    """Show backend details and configuration.
+
+    \b
+    Examples:
+        forge backend show litellm-4000
+    """
+    console = Console(width=200)
+    store = BackendRegistryStore()
+
+    # Parse adapter type from backend_id (e.g., "litellm-4000" -> "litellm")
+    parts = backend_id.rsplit("-", 1)
+    adapter_type = parts[0] if len(parts) == 2 else backend_id
+
+    try:
+        registry = store.read()
+        instance = registry.backends.get(backend_id)
+        if instance:
+            alive = instance.pid is not None and is_pid_alive(instance.pid)
+            status_color = "green" if alive else "yellow"
+            console.print(f"[bold]Backend:[/bold] [cyan]{backend_id}[/cyan]")
+            console.print(f"[bold]Adapter:[/bold] {instance.adapter_type}")
+            console.print(f"[bold]Port:[/bold] {instance.port}")
+            console.print(f"[bold]PID:[/bold] {instance.pid or '-'}")
+            console.print(
+                f"[bold]Status:[/bold] [{status_color}]{'healthy' if alive else 'not running'}[/{status_color}]"
+            )
+            if instance.created_at:
+                console.print(f"[bold]Started:[/bold] {instance.created_at}")
+        else:
+            console.print(f"[bold]Backend:[/bold] [cyan]{backend_id}[/cyan] [dim](not in registry)[/dim]")
+    except Exception:
+        console.print(f"[bold]Backend:[/bold] [cyan]{backend_id}[/cyan]")
+
+    log_file = get_forge_home() / "logs" / "backend" / f"{backend_id}.log"
+    if log_file.exists():
+        console.print(f"[bold]Log:[/bold] {display_path(log_file)}")
+    else:
+        log_file = (
+            get_forge_home() / "logs" / "backend" / f"{adapter_type}-{parts[1] if len(parts) == 2 else '4000'}.log"
+        )
+        if log_file.exists():
+            console.print(f"[bold]Log:[/bold] {display_path(log_file)}")
+
+    config_path = get_backend_config_path(adapter_type)
+    if config_path.exists():
+        content = config_path.read_text()
+        console.print(f"[bold]Config:[/bold] {display_path(config_path)}\n")
+        if raw:
+            console.print(content)
+        else:
+            from rich.syntax import Syntax
+
+            syntax = Syntax(content, "yaml", theme="monokai", line_numbers=True)
+            console.print(syntax)
+    else:
+        console.print(f"\n[dim]No config found for adapter '{adapter_type}'.[/dim]")
+        console.print(f"[dim]Tip: Run 'forge backend create {adapter_type}'.[/dim]")
+
+
+@backend.command("create")
+@click.argument("adapter", type=click.Choice(["litellm"]))
+@click.option(
+    "--config",
+    "-c",
+    type=Path,
+    help="Source config file (defaults to installed template)",
+)
+def create_cmd(adapter: str, config: Path | None) -> None:
+    """Create a backend config (copy to installed location).
+
+    Config is shared by all instances of this adapter type.
+    """
+    console = Console(width=200)
+
+    config_path = get_backend_config_path(adapter)
+    if config_path.exists():
+        console.print(f"[yellow]Backend config already exists:[/yellow] {display_path(config_path)}")
+        console.print("\n[dim]Start an instance with:[/dim]")
+        console.print(f"  forge backend start {adapter} --port 4000")
+        return
+
+    try:
+        config_path = create_backend_config(
+            adapter_type=adapter,
+            source_config=config,
+        )
+        console.print(f"[green]Created[/green] backend config for '{adapter}'")
+        console.print(f"  Config: {display_path(config_path)}")
+        console.print("\n[dim]Start an instance with:[/dim]")
+        console.print(f"  forge backend start {adapter} --port 4000")
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+
+@backend.command("start")
+@click.argument("adapter", type=click.Choice(["litellm"]))
+@click.option("--port", "-p", type=int, required=True, help="Port number")
+def start_cmd(adapter: str, port: int) -> None:
+    """Start a backend instance."""
+    console = Console(width=200)
+
+    config_path = get_backend_config_path(adapter)
+    if not config_path.exists():
+        console.print(f"[red]Error:[/red] Backend config not found for '{adapter}'")
+        console.print("\n[dim]Create it first:[/dim]")
+        console.print(f"  forge backend create {adapter}")
+        sys.exit(1)
+
+    backend_id = f"{adapter}-{port}"
+    store = BackendRegistryStore()
+    manager = BackendManager(store)
+    manager.register_adapter(adapter, get_adapter(adapter))
+
+    try:
+        result = manager.ensure_backend(backend_id, adapter, port)
+        if result.source == "start":
+            console.print(f"[green]Started[/green] backend '{backend_id}' on port {port} (pid {result.instance.pid})")
+        else:
+            console.print(f"Backend '{backend_id}' already running on port {port}")
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+
+@backend.command("stop")
+@click.argument("adapter", type=click.Choice(["litellm"]))
+@click.option("--port", "-p", type=int, required=True, help="Port number")
+def stop_cmd(adapter: str, port: int) -> None:
+    """Stop a backend instance."""
+    console = Console(width=200)
+    backend_id = f"{adapter}-{port}"
+
+    store = BackendRegistryStore()
+    manager = BackendManager(store)
+    manager.register_adapter(adapter, get_adapter(adapter))
+
+    try:
+        manager.stop_backend(backend_id)
+        console.print(f"[green]Stopped[/green] backend '{backend_id}'")
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+
+@backend.command("delete")
+@click.argument("adapter", type=click.Choice(["litellm"]))
+@click.option(
+    "--port",
+    "-p",
+    type=int,
+    help="Delete specific instance (if not specified, deletes config)",
+)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
+@click.option("--force", "-f", is_flag=True, hidden=True, help="Deprecated alias for --yes")
+def delete_cmd(adapter: str, port: int | None, yes: bool, force: bool) -> None:
+    """Delete a backend instance or config.
+
+    Without --port: Deletes the backend config (stops all instances first).
+    With --port: Stops and unregisters specific instance (keeps config).
+    """
+    import shutil
+
+    yes = yes or force
+    console = Console(width=200)
+
+    if port is not None:
+        backend_id = f"{adapter}-{port}"
+        if not yes and not click.confirm(f"Stop backend instance '{backend_id}'?"):
+            console.print("Cancelled.")
+            return
+
+        try:
+            stop_cmd.callback(adapter, port)  # type: ignore[misc]  # click.Command.callback is Optional[Callable]; always set here
+            console.print(f"[green]Stopped[/green] backend instance '{backend_id}'")
+        except Exception as e:
+            console.print(f"[red]Error:[/red] {e}")
+            sys.exit(1)
+    else:
+        backend_dir = get_forge_home() / "backends" / adapter
+        if not backend_dir.exists():
+            console.print(f"[red]Error:[/red] Backend config not found for '{adapter}'")
+            sys.exit(1)
+
+        if not yes and not click.confirm(f"Delete backend config for '{adapter}' (stops all instances)?"):
+            console.print("Cancelled.")
+            return
+
+        store = BackendRegistryStore()
+        registry = store.read()
+        stopped = []
+        for backend_id in list(registry.backends.keys()):
+            if backend_id.startswith(f"{adapter}-"):
+                try:
+                    # Use rsplit to handle adapter names with hyphens (e.g., "some-adapter-4000")
+                    port_str = backend_id.rsplit("-", 1)[1]
+                    stop_cmd.callback(adapter, int(port_str))  # type: ignore[misc]  # click.Command.callback is Optional[Callable]; always set here
+                    stopped.append(backend_id)
+                except Exception:
+                    pass
+
+        if stopped:
+            console.print(f"Stopped instances: {', '.join(stopped)}")
+
+        shutil.rmtree(backend_dir)
+        console.print(f"[green]Deleted[/green] backend config for '{adapter}'")

forge/cli/claude.py

@@ -0,0 +1,411 @@
+"""Claude Code management commands.
+
+Commands:
+- forge claude start --proxy <id> - Start Claude with specific proxy
+- forge claude start --no-proxy   - Start Claude without proxy
+- forge claude preset         - Manage settings preset
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+import httpx
+from rich.console import Console
+
+from forge.core.paths import display_path
+from forge.proxy.proxies import (
+    ProxyRegistryCorruptedError,
+    ProxyRegistryStore,
+    ProxyResolutionError,
+    resolve_proxy,
+)
+from forge.session.direct_model import apply_direct_model_env
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+def _default_context_limit() -> int:
+    from forge.runtime_config import get_runtime_config
+
+    return get_runtime_config().context_limit
+
+
+def _get_context_limit_for_proxy(proxy_id: str) -> int:
+    """Compute context limit from proxy's default tier model.
+
+    Deterministic: uses the specific proxy_id to look up the exact model config,
+    unlike the heuristic _get_context_limit_for_template() in session.py which
+    picks the first matching template.
+    """
+    try:
+        from forge.config.loader import load_proxy_instance_config
+        from forge.core.models import get_context_window_tokens
+
+        proxy_config = load_proxy_instance_config(proxy_id)
+        if proxy_config is None:
+            logger.debug(f"No proxy config found for {proxy_id}, using default context limit")
+            return _default_context_limit()
+
+        tier = proxy_config.default_tier or "sonnet"
+
+        model = proxy_config.tiers.get(tier)
+        if not model:
+            logger.debug(f"No model found for tier {tier}, using default context limit")
+            return _default_context_limit()
+
+        context_limit = get_context_window_tokens(model)
+        logger.debug(f"Computed context limit {context_limit} for model {model} (tier {tier})")
+        return context_limit
+
+    except Exception as e:
+        logger.debug(f"Failed to compute context limit: {e}, using default")
+        return _default_context_limit()
+
+
+def _healthcheck_proxy(*, base_url: str, expected_template: str, expected_proxy_id: str) -> None:
+    """Validate proxy is reachable and matches proxy identity."""
+
+    url = base_url.rstrip("/") + "/"
+
+    try:
+        response = httpx.get(url, timeout=2.0)
+    except httpx.ConnectError:
+        raise ValueError(f"proxy is not running (connection refused at {url})")
+    except httpx.RequestError as e:
+        raise ValueError(f"proxy healthcheck failed at {url}: {e}")
+
+    if response.status_code != 200:
+        raise ValueError(f"proxy healthcheck failed at {url}: status {response.status_code}")
+
+    try:
+        data = response.json()
+    except ValueError as e:
+        raise ValueError(f"proxy healthcheck failed at {url}: invalid JSON: {e}")
+
+    if not isinstance(data, dict):
+        raise ValueError(f"proxy healthcheck failed at {url}: expected JSON object")
+
+    if data.get("is_proxy") is not True:
+        raise ValueError(f"proxy healthcheck failed at {url}: is_proxy is not true")
+
+    template = data.get("template")
+    if template != expected_template:
+        raise ValueError(
+            f"proxy healthcheck failed at {url}: template mismatch (expected '{expected_template}', got '{template}')"
+        )
+
+    proxy_block = data.get("proxy")
+    if not isinstance(proxy_block, dict):
+        raise ValueError(f"proxy healthcheck failed at {url}: missing proxy block")
+
+    actual_proxy_id = proxy_block.get("proxy_id")
+    if actual_proxy_id != expected_proxy_id:
+        raise ValueError(
+            f"proxy healthcheck failed at {url}: proxy_id mismatch (expected '{expected_proxy_id}', got '{actual_proxy_id}')"
+        )
+
+
+# --- Group and Commands ---
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+def claude() -> None:
+    """Start and manage Claude Code.
+
+    \b
+    Examples:
+        forge claude start --proxy my-proxy    # Start with specific proxy
+        forge claude start --no-proxy           # Start without proxy (direct to Anthropic)
+    """
+    pass
+
+
+def _build_bare_launch_env(
+    *,
+    base_url: str | None,
+    template: str | None,
+    context_limit: int | None,
+) -> tuple[dict[str, str], list[str]]:
+    """Build environment for bare Claude launch (no session state).
+
+    Returns (env_vars_to_set, env_vars_to_unset).  Always scrubs session
+    identity vars so a nested ``forge claude start`` never inherits a
+    parent session.
+    """
+    env_vars: dict[str, str] = {}
+    unset_vars: list[str] = ["FORGE_SESSION", "FORGE_FORK_NAME", "FORGE_PARENT_SESSION"]
+
+    if base_url is None:
+        # Direct mode: don't touch CLAUDE_CODE_AUTO_COMPACT_WINDOW — it's a
+        # native CC env var the user may have set. Only scrub Forge-managed vars.
+        unset_vars.extend(["ANTHROPIC_BASE_URL", "ACTIVE_TEMPLATE"])
+    else:
+        env_vars["ANTHROPIC_BASE_URL"] = base_url
+        if context_limit is not None:
+            env_vars["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = str(context_limit)
+        if template:
+            env_vars["ACTIVE_TEMPLATE"] = template
+        else:
+            unset_vars.append("ACTIVE_TEMPLATE")
+
+    return env_vars, unset_vars
+
+
+@claude.command("start")
+@click.option(
+    "--proxy",
+    "proxy_id",
+    type=str,
+    default=None,
+    help="Proxy to use (proxy_id or template name)",
+)
+@click.option(
+    "--no-proxy",
+    "direct",
+    is_flag=True,
+    default=False,
+    help="Bypass the proxy and talk to Anthropic directly",
+)
+@click.argument("claude_args", nargs=-1, type=click.UNPROCESSED)
+def start_cmd(
+    proxy_id: str | None,
+    direct: bool,
+    claude_args: tuple[str, ...],
+) -> None:
+    """Start Claude Code with proxy routing or direct to Anthropic.
+
+    Bare launcher: no session state, no FORGE_SESSION.  Use
+    ``forge session start`` for managed sessions with lifecycle tracking.
+
+    \b
+    Examples:
+        forge claude start --proxy my-proxy
+        forge claude start --no-proxy
+        forge claude start --proxy my-proxy -- --debug
+    """
+    if direct and proxy_id:
+        click.echo("Error: --no-proxy and --proxy are mutually exclusive")
+        sys.exit(1)
+    if not direct and not proxy_id:
+        click.echo("Error: one of --proxy or --no-proxy is required")
+        sys.exit(1)
+
+    from forge.session.claude.invoke import invoke_claude
+
+    # Resolve proxy to template + base_url
+    template: str | None = None
+    base_url: str | None = None
+    context_limit: int | None = None
+    proxy_display: str | None = None
+
+    if proxy_id:
+        proxy_store = ProxyRegistryStore()
+
+        try:
+            registry = proxy_store.read()
+        except ProxyRegistryCorruptedError as e:
+            click.echo(f"Error: {e}")
+            sys.exit(1)
+
+        try:
+            entry = resolve_proxy(registry, proxy_id)
+        except ProxyResolutionError as e:
+            click.echo(f"Error: {e}")
+            sys.exit(1)
+
+        try:
+            _healthcheck_proxy(
+                base_url=entry.base_url,
+                expected_template=entry.template,
+                expected_proxy_id=entry.proxy_id,
+            )
+        except ValueError as e:
+            click.echo(f"Error: {e}")
+            if "not running" in str(e):
+                click.echo(f"Tip: Run 'forge proxy start {entry.proxy_id}' to start it.")
+            sys.exit(1)
+
+        template = entry.template
+        base_url = entry.base_url
+        context_limit = _get_context_limit_for_proxy(entry.proxy_id)
+        proxy_display = entry.proxy_id
+
+    env_vars, unset_vars = _build_bare_launch_env(
+        base_url=base_url,
+        template=template,
+        context_limit=context_limit,
+    )
+
+    if direct:
+        from forge.runtime_config import get_default_direct_model
+
+        direct_model = get_default_direct_model()
+        error = apply_direct_model_env(env_vars, direct_model)
+        if error:
+            click.echo(f"Error: {error}")
+            sys.exit(1)
+
+    if proxy_display:
+        console.print(f"Starting Claude with proxy [green]{proxy_display}[/green] ({template})")
+    else:
+        console.print("Starting Claude [green]direct[/green] (no proxy)")
+
+    from forge.cli.session_addendum import (
+        resolve_addendum_content_for_proxy,
+        write_bare_addendum,
+    )
+
+    addendum_content = resolve_addendum_content_for_proxy(proxy_display)
+    addendum_path: Path | None = None
+    if addendum_content:
+        addendum_path = write_bare_addendum(addendum_content)
+
+    try:
+        sys.exit(
+            invoke_claude(
+                model=None,
+                system_prompt_file=str(addendum_path) if addendum_path else None,
+                env_vars=env_vars,
+                unset_env_vars=unset_vars,
+                extra_args=list(claude_args) if claude_args else None,
+            )
+        )
+    finally:
+        if addendum_path:
+            addendum_path.unlink(missing_ok=True)
+
+
+# --- Preset subgroup ---
+
+
+@claude.group("preset")
+def preset() -> None:
+    """Manage Claude Code settings preset.
+
+    \b
+    The preset (~/.forge/claude.preset.json) controls what settings
+    Forge merges into Claude Code's settings.json on enable/sync.
+
+    \b
+    Examples:
+        forge claude preset show         # Show current preset
+        forge claude preset edit         # Open in $EDITOR
+        forge claude preset reset        # Reset to built-in defaults
+    """
+
+
+@preset.command("show")
+@click.option("--raw", is_flag=True, help="Output raw JSON without syntax highlighting")
+def preset_show(raw: bool = False) -> None:
+    """Show current Claude Code settings preset."""
+    from rich.syntax import Syntax
+
+    from forge.install.preset import ensure_preset, get_preset_path
+
+    preset_path = get_preset_path()
+    ensure_preset()
+
+    content = preset_path.read_text(encoding="utf-8")
+
+    if raw:
+        console.print(content, end="")
+    else:
+        console.print("[bold]Claude Code Settings Preset[/bold]")
+        console.print(f"[bold]Path:[/bold] {display_path(preset_path)}")
+        console.print()
+        syntax = Syntax(content, "json", theme="monokai")
+        console.print(syntax)
+
+
+@preset.command("edit")
+def preset_edit() -> None:
+    """Open settings preset in $EDITOR.
+
+    Creates the file with built-in defaults if it doesn't exist.
+    Validates JSON before saving.
+    """
+    import json
+    import shutil
+    import tempfile
+
+    from forge.install.preset import ensure_preset, get_preset_path
+
+    preset_path = get_preset_path()
+    ensure_preset()
+
+    editor = os.environ.get("EDITOR", "vim")
+    if not shutil.which(editor):
+        console.print(f"[red]Error:[/red] Editor '{editor}' not found. Set $EDITOR to an available editor.")
+        sys.exit(1)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as tmp:
+        tmp.write(preset_path.read_text(encoding="utf-8"))
+        tmp_path = Path(tmp.name)
+
+    success = False
+    try:
+        result = subprocess.run([editor, str(tmp_path)])
+        if result.returncode != 0:
+            console.print(f"[red]Error:[/red] Editor exited with code {result.returncode}")
+            console.print(f"Your changes are saved at: {display_path(tmp_path)}")
+            sys.exit(1)
+
+        try:
+            with open(tmp_path, encoding="utf-8") as f:
+                edited_data = json.load(f)
+        except json.JSONDecodeError as e:
+            console.print(f"[red]Error:[/red] Invalid JSON: {e}")
+            console.print(f"Your changes are saved at: {display_path(tmp_path)}")
+            sys.exit(1)
+
+        if not isinstance(edited_data, dict):
+            console.print("[red]Error:[/red] Preset must be a JSON object")
+            console.print(f"Your changes are saved at: {display_path(tmp_path)}")
+            sys.exit(1)
+
+        from forge.core.state import atomic_write_text
+
+        content = json.dumps(edited_data, indent=2) + "\n"
+        atomic_write_text(preset_path, content)
+        os.chmod(str(preset_path), 0o600)
+
+        success = True
+        console.print("[green]Updated[/green] settings preset")
+
+    finally:
+        if success and tmp_path.exists():
+            try:
+                tmp_path.unlink()
+            except OSError:
+                pass
+
+
+@preset.command("reset")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
+@click.option("--force", "-f", is_flag=True, hidden=True, help="Deprecated alias for --yes")
+def preset_reset(yes: bool, force: bool) -> None:
+    """Reset settings preset to built-in defaults."""
+    from forge.core.state import atomic_write_text
+    from forge.install.preset import get_builtin_preset_json, get_preset_path
+
+    yes = yes or force
+    preset_path = get_preset_path()
+
+    if not yes:
+        if not click.confirm("Reset preset to built-in defaults?"):
+            console.print("[dim]Cancelled.[/dim]")
+            return
+
+    preset_path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(preset_path, get_builtin_preset_json())
+    os.chmod(str(preset_path), 0o600)
+    console.print("[green]Reset[/green] preset to built-in defaults")