fadenstack 0.4.2__py3-none-any.whl

faden_cli/commands/doctor.py

@@ -0,0 +1,225 @@
+"""``faden doctor`` — diagnose the host environment.
+
+Runs comprehensive checks on the system and reports whether all
+prerequisites are satisfied for running Fadenstack.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.panel import Panel
+from rich.table import Table
+
+from faden_cli.core.console import console
+from faden_cli.core.detect import (
+    check_install_ports,
+    full_report,
+)
+
+
+def _check_mark(ok: bool) -> str:
+    return "[green]✓[/green]" if ok else "[red]✗[/red]"
+
+
+@click.command("doctor")
+@click.option("--ports/--no-ports", default=True, help="Check port availability.")
+@click.pass_context
+def doctor_cmd(ctx: click.Context, *, ports: bool) -> None:
+    """Run system health checks and report readiness."""
+    verbose = ctx.obj.get("verbose", False)
+
+    with console.status("[bold cyan]Running diagnostics…[/bold cyan]"):
+        report = full_report(check_ports=False)
+        port_checks = check_install_ports(*_install_compose()) if ports else []
+
+    # ── OS ────────────────────────────────────────────────────────
+    os_info = report.os
+    console.print(
+        Panel(
+            f"[bold]{os_info.system}[/bold] {os_info.release} — {os_info.machine}",
+            title="Operating System",
+            border_style="cyan",
+        )
+    )
+
+    # ── RAM ───────────────────────────────────────────────────────
+    ram = report.ram
+    # An "8 GB" machine reports 7.5-7.8 GB once the kernel has its share;
+    # the release test VM ran everything in 7 GB.
+    ram_ok = ram.total_gb >= 7.0
+    console.print(
+        f"\n{_check_mark(ram_ok)}  RAM: [bold]{ram.total_gb:.1f} GB[/bold] total, "
+        f"{ram.available_gb:.1f} GB available  "
+        f"{'(8 GB recommended)' if not ram_ok else ''}"
+    )
+
+    # ── Disk ──────────────────────────────────────────────────────
+    disk = report.disk
+    disk_ok = disk.free_gb >= 20.0
+    console.print(
+        f"{_check_mark(disk_ok)}  Disk: [bold]{disk.free_gb:.1f} GB[/bold] free of "
+        f"{disk.total_gb:.1f} GB  "
+        f"{'(≥20 GB recommended)' if not disk_ok else ''}"
+    )
+
+    # ── Docker ────────────────────────────────────────────────────
+    docker = report.docker
+    docker_ver = docker.version or f'[red]not found[/red]  → {docker.install_hint}'
+    console.print(
+        f"\n{_check_mark(docker.installed)}  Docker: "
+        f"{docker_ver}"
+    )
+    if docker.installed and not docker.daemon_running and docker.error:
+        console.print(f"   [dim]{docker.error}[/dim]")
+    compose_ver = docker.compose_version or f'[red]not found[/red]  → {docker.install_hint}'
+    console.print(
+        f"{_check_mark(docker.compose_installed)}  Compose: "
+        f"{compose_ver}"
+    )
+    console.print(
+        f"{_check_mark(docker.daemon_running)}  Docker daemon: "
+        f"{'running' if docker.daemon_running else '[red]not running[/red]'}"
+    )
+
+    # ── GPU ───────────────────────────────────────────────────────
+    # The server needs no GPU: models run on the machines added to it.
+    gpu = report.gpu
+    if gpu.has_gpu:
+        for dev in gpu.devices:
+            console.print(
+                f"[cyan]i[/cyan]  GPU: [bold]{dev.name}[/bold] "
+                f"({dev.vram_mb} MB) -- add this server as a machine to use it"
+            )
+    else:
+        console.print("[cyan]i[/cyan]  GPU: none on this server (models run on the machines you add)")
+
+    # ── Ports ─────────────────────────────────────────────────────
+    # Developer tools (git, uv, node) are `faden dev doctor`'s: a server
+    # running the published images needs none of them.
+    conflicts = [pc for pc in port_checks if pc.in_use and not pc.ours]
+    if port_checks:
+        console.print()
+        port_table = Table(title="Ports this install publishes", show_header=True, header_style="bold")
+        port_table.add_column("Port", justify="right")
+        port_table.add_column("Service")
+        port_table.add_column("Status")
+
+        for pc in port_checks:
+            if not pc.in_use:
+                status = "[green]available[/green]"
+            elif pc.ours:
+                status = "[green]Fadenstack[/green]"
+            else:
+                status = "[red]in use by something else[/red]"
+            port_table.add_row(str(pc.port), pc.label, status)
+        console.print(port_table)
+        if conflicts:
+            console.print(
+                "[dim]  A port held by something else stops `faden deploy`: free it, or change\n"
+                "  the port (faden ports --http/--https; PROM_PORT, ... in .env).[/dim]"
+            )
+
+    # ── HTTPS ─────────────────────────────────────────────────────
+    _https_check()
+
+    # ── Release ───────────────────────────────────────────────────
+    _release_check()
+
+    # ── Verdict ───────────────────────────────────────────────────
+    all_ok = (
+        docker.installed
+        and docker.compose_installed
+        and docker.daemon_running
+        and ram_ok
+        and disk_ok
+        and not conflicts
+    )
+    console.print()
+    if all_ok:
+        console.print("[bold green]All core prerequisites met.[/bold green] ✨")
+    else:
+        console.print("[bold red]Some prerequisites are missing — see above.[/bold red]")
+
+    console.print("[dim]Developer tools: faden dev doctor[/dim]")
+    if verbose:
+        console.print(f"\n[dim]Report generated with {len(port_checks)} port checks.[/dim]")
+
+
+def _install_compose() -> tuple[Path | None, Path | None]:
+    """The compose file and .env of the configured install, or of this CLI's release."""
+    from faden_cli.core.bundle import bundled_files  # noqa: PLC0415
+    from faden_cli.core.settings import load_config  # noqa: PLC0415
+
+    cfg = load_config()
+    if cfg.install_dir and cfg.compose_path.is_file():
+        return cfg.compose_path, cfg.env_path
+    bundled = bundled_files()
+    if bundled is not None:
+        return Path(str(bundled / "docker-compose.yaml")), None
+    return None, None
+
+
+def _release_check() -> None:
+    """Whether a newer release is out (the release feed, read now; the last check when offline)."""
+    from faden_cli import __version__  # noqa: PLC0415
+    from faden_cli.core import release_feed, update_check  # noqa: PLC0415
+    from faden_cli.core.settings import load_config  # noqa: PLC0415
+
+    cfg = load_config()
+    if not update_check.enabled(cfg):
+        console.print(f"{_check_mark(True)}  Release: {__version__} (update check off)")
+        return
+    try:
+        feed: release_feed.Feed | None = update_check.refresh(cfg)
+    except Exception as exc:  # offline is reported, not fatal
+        feed = update_check.cached_feed()
+        console.print(f"[cyan]i[/cyan]  Release feed not reachable ({exc}); showing the last check")
+    if feed is None:
+        console.print(f"[cyan]i[/cyan]  Release: {__version__} (never checked)")
+        return
+    found = release_feed.assess(feed, __version__, cfg.update_channel)
+    if found.unsupported:
+        console.print(
+            f"{_check_mark(False)}  Release: {__version__} no longer gets fixes "
+            f"(since {found.supported_until})"
+        )
+    if not found.update_available or found.latest is None:
+        if not found.unsupported:
+            console.print(f"{_check_mark(True)}  Release: {__version__}, the newest")
+        return
+    urgent = found.severity in ("security", "critical")
+    console.print(
+        f"{_check_mark(not urgent)}  Release: {__version__}; {found.latest.version} is available"
+        f"{f' ({found.severity})' if found.severity != 'normal' else ''}"
+        " -- faden version shows how to upgrade"
+    )
+
+
+def _https_check() -> None:
+    """HTTPS on or off, how long the certificate lasts, and whether it renews by itself."""
+    from datetime import UTC, datetime  # noqa: PLC0415
+
+    from faden_cli.commands.tls import renewal_scheduled  # noqa: PLC0415
+    from faden_cli.core import tls  # noqa: PLC0415
+    from faden_cli.core.settings import load_config  # noqa: PLC0415
+
+    cfg = load_config()
+    if not cfg.install_dir:
+        return
+    try:
+        served = tls.current(Path(cfg.install_dir))
+    except tls.TlsError as exc:
+        console.print(f"\n{_check_mark(False)}  HTTPS: {exc}")
+        return
+    if served is None:
+        console.print(f"\n{_check_mark(True)}  HTTPS: off (faden tls generate switches it on)")
+        return
+    left = (served.not_after - datetime.now(UTC)).days
+    renews = renewal_scheduled() and (served.made_here or tls.source(Path(cfg.install_dir)) is not None)
+    ok = left >= tls.EXPIRY_WARNING_DAYS or (renews and left > 0)
+    how = "renews by itself" if renews else "renewed by hand (faden tls status)"
+    console.print(
+        f"\n{_check_mark(ok)}  HTTPS: on until [bold]{served.not_after:%Y-%m-%d}[/bold] ({left} days), {how}"
+    )

faden_cli/commands/down.py

@@ -0,0 +1,75 @@
+"""``faden down`` — stop Fadenstack services."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+
+import click
+
+from faden_cli.core.compose import build_context_from_config, down as compose_down
+from faden_cli.core.console import console, success, error, info
+from faden_cli.core.settings import load_config
+
+# Image prefixes that belong to the project (built from source).
+_PROJECT_IMAGE_PREFIX = "ghcr.io/fadenstack/"
+
+
+def _remove_project_images() -> int:
+    """Remove only locally-built faden/* images. Return count removed."""
+    docker = shutil.which("docker")
+    if not docker:
+        return 0
+    result = subprocess.run(  # noqa: S603
+        [docker, "images", "--format", "{{.Repository}}:{{.Tag}}",
+         "--filter", f"reference={_PROJECT_IMAGE_PREFIX}*"],
+        capture_output=True, text=True,
+    )
+    images = [img for img in result.stdout.strip().splitlines() if img]
+    if not images:
+        return 0
+    subprocess.run([docker, "image", "rm", "-f", *images],  # noqa: S603
+                   capture_output=True, text=True)
+    return len(images)
+
+
+@click.command("down")
+@click.option("--volumes/--no-volumes", default=False, help="Remove named volumes declared in the compose file.")
+@click.option("--remove-orphans/--no-remove-orphans", default=True, help="Remove containers for services not defined in the compose file.")
+@click.option("--all", "nuke", is_flag=True, help="Remove everything: containers, networks, volumes, and built images (keeps third-party images).")
+def down_cmd(*, volumes: bool, remove_orphans: bool, nuke: bool) -> None:
+    """Stop and remove Fadenstack containers and networks."""
+    cfg = load_config()
+    ctx = build_context_from_config(cfg)
+
+    if nuke:
+        volumes = True
+
+    console.print("[bold cyan]Stopping Fadenstack services…[/bold cyan]")
+
+    with console.status("[bold cyan]docker compose down[/bold cyan]"):
+        returncode = compose_down(
+            ctx,
+            volumes=volumes,
+            remove_orphans=remove_orphans,
+        )
+
+    if returncode == 0:
+        success("Services stopped.")
+    else:
+        error(f"docker compose down exited with code {returncode}.")
+        sys.exit(returncode)
+
+    if nuke:
+        removed = _remove_project_images()
+        if removed:
+            info(f"Removed {removed} faden image(s).")
+        else:
+            info("No faden images to remove.")
+
+        # Stop and remove the local node agent if present.
+        from faden_cli.core.local_node import remove_local_node_agent  # noqa: PLC0415
+
+        workspace = cfg.install_path.parent
+        remove_local_node_agent(workspace=workspace)

faden_cli/commands/logs_cmd.py

@@ -0,0 +1,41 @@
+"""``faden logs`` — stream container logs."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from faden_cli.core.compose import build_context_from_config, logs as compose_logs
+from faden_cli.core.settings import load_config
+
+
+@click.command("logs")
+@click.option("-f", "--follow", is_flag=True, help="Follow log output.")
+@click.option("-n", "--tail", default=100, show_default=True, help="Number of lines to show from the end.")
+@click.option("--timestamps/--no-timestamps", default=False, help="Show timestamps.")
+@click.argument("services", nargs=-1)
+def logs_cmd(
+    *,
+    follow: bool,
+    tail: int,
+    timestamps: bool,
+    services: tuple[str, ...],
+) -> None:
+    """View logs from Fadenstack services.
+
+    Pass one or more SERVICE names to filter, or omit to see all.
+    """
+    cfg = load_config()
+    ctx = build_context_from_config(cfg)
+
+    returncode = compose_logs(
+        ctx,
+        services=list(services) if services else None,
+        follow=follow,
+        tail=tail,
+        timestamps=timestamps,
+    )
+
+    if returncode != 0:
+        sys.exit(returncode)

faden_cli/commands/maintenance.py

@@ -0,0 +1,74 @@
+"""``faden maintenance`` — show the maintenance page instead of the platform.
+
+Examples:
+    faden maintenance on                          # every page says "under maintenance"
+    faden maintenance on -m "Back at 15:00"       # ... with a note for the users
+    faden maintenance status
+    faden maintenance off
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from faden_cli.core import maintenance
+from faden_cli.core.console import console, error, info, success
+from faden_cli.core.settings import load_config
+
+
+def _install_dir() -> Path:
+    cfg = load_config()
+    if not cfg.install_dir:
+        error(
+            "No install directory configured.\n"
+            "  Run 'faden deploy' first, or set install_dir in faden.yaml."
+        )
+        sys.exit(1)
+    return cfg.install_path
+
+
+@click.group("maintenance")
+def maintenance_group() -> None:
+    """Switch the maintenance page on or off.
+
+    While it is on, nginx answers every page with a maintenance page that
+    reloads itself once maintenance ends, and the APIs (/api, /v1) with 503.
+    The services keep running; only the front door changes. `faden upgrade`
+    does this by itself for its restart.
+    """
+
+
+@maintenance_group.command("on")
+@click.option("-m", "--message", default=None, help="A note shown on the page, e.g. when it will be back.")
+def on_cmd(*, message: str | None) -> None:
+    """Answer every page with the maintenance page."""
+    install_dir = _install_dir()
+    path = maintenance.enter(install_dir, reason="manual", message=message)
+    success(f"Maintenance on: every page now shows the maintenance page ({path}).")
+    info("Switch it off with: faden maintenance off")
+
+
+@maintenance_group.command("off")
+def off_cmd() -> None:
+    """Back to the platform."""
+    if maintenance.leave(_install_dir()):
+        success("Maintenance off: the platform answers again.")
+    else:
+        info("Maintenance was not on.")
+
+
+@maintenance_group.command("status")
+def status_cmd() -> None:
+    """Whether the maintenance page is up, since when and why."""
+    found = maintenance.state(_install_dir())
+    if found is None:
+        console.print("Maintenance: [green]off[/green]")
+        return
+    console.print(
+        f"Maintenance: [yellow]on[/yellow] ({found.get('reason', 'manual')}, since {found.get('since', '?')})"
+    )
+    if found.get("message"):
+        console.print(f"  Note: {found['message']}")

faden_cli/commands/module.py

@@ -0,0 +1,113 @@
+"""``faden module`` — enable / disable optional platform modules."""
+
+from __future__ import annotations
+
+import click
+from rich.table import Table
+
+from faden_cli.core.console import console, info, success, warning
+from faden_cli.core.env_gen import set_module_env
+from faden_cli.core.registry import MODULES_COMPAT as MODULES
+from faden_cli.core.settings import FadenConfig, load_config, save_config
+
+
+def _write_env(cfg: FadenConfig, *, enable: list[str], disable: list[str]) -> None:
+    """Carry the change into the install's ``.env``, where the services read it.
+
+    Recording a module in faden.yaml only starts its containers; the
+    gateway and the backend switch it on from ``.env``.
+    """
+    env_path = cfg.install_path / ".env"
+    if not env_path.exists():
+        return
+    changed = set_module_env(env_path, enable=enable, disable=disable)
+    if changed:
+        info(f"Updated {env_path}: {', '.join(sorted(changed))}")
+
+
+@click.group("module")
+def module_group() -> None:
+    """Manage optional Fadenstack modules (pii, mcp, skills)."""
+
+
+@module_group.command("list")
+def module_list() -> None:
+    """List available modules and their status."""
+    cfg = load_config()
+    active_profiles = set(cfg.profiles or [])
+
+    table = Table(
+        title="Fadenstack Modules",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Module", style="bold")
+    table.add_column("Status")
+    table.add_column("Description")
+
+    for name, module in MODULES.items():
+        enabled = module["profile"] in active_profiles
+        status = "[green]enabled[/green]" if enabled else "[dim]disabled[/dim]"
+        table.add_row(name, status, module["description"])
+
+    console.print(table)
+
+
+@module_group.command("enable")
+@click.argument("modules", nargs=-1, required=True)
+def module_enable(modules: tuple[str, ...]) -> None:
+    """Enable one or more modules.
+
+    Example: faden module enable pii auth
+    """
+    cfg = load_config()
+    profiles = set(cfg.profiles or [])
+    enabled: list[str] = []
+
+    for mod in modules:
+        mod_lower = mod.lower()
+        if mod_lower not in MODULES:
+            warning(f"Unknown module: {mod_lower}. Available: {', '.join(MODULES)}")
+            continue
+        profile = MODULES[mod_lower]["profile"]
+        profiles.add(profile)
+        enabled.append(mod_lower)
+        success(f"Enabled module: {mod_lower}")
+
+    cfg.profiles = sorted(profiles)
+    save_config(cfg)
+    _write_env(cfg, enable=enabled, disable=[])
+    console.print(
+        "\n[dim]Run [bold]faden up[/bold] to apply changes "
+        "(or [bold]faden dev up[/bold] in a dev workspace).[/dim]",
+    )
+
+
+@module_group.command("disable")
+@click.argument("modules", nargs=-1, required=True)
+def module_disable(modules: tuple[str, ...]) -> None:
+    """Disable one or more modules.
+
+    Example: faden module disable pii
+    """
+    cfg = load_config()
+    profiles = set(cfg.profiles or [])
+    disabled: list[str] = []
+
+    for mod in modules:
+        mod_lower = mod.lower()
+        if mod_lower not in MODULES:
+            warning(f"Unknown module: {mod_lower}. Available: {', '.join(MODULES)}")
+            continue
+        profile = MODULES[mod_lower]["profile"]
+        profiles.discard(profile)
+        disabled.append(mod_lower)
+        success(f"Disabled module: {mod_lower}")
+
+    cfg.profiles = sorted(profiles)
+    save_config(cfg)
+    _write_env(cfg, enable=[], disable=disabled)
+    console.print(
+        "\n[dim]Run [bold]faden down && faden up[/bold] to apply changes "
+        "(or [bold]faden dev up[/bold] in a dev workspace).[/dim]",
+    )

faden_cli/commands/observe.py

@@ -0,0 +1,95 @@
+"""``faden observe`` — observability commands for cost tracking."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+import httpx
+
+from faden_cli.core.api_client import ApiClient
+from faden_cli.core.console import console, error, info, success
+from faden_cli.core.settings import load_config
+
+
+def _ensure_token(cfg) -> str | None:
+    """Return the configured API token, or prompt for login credentials."""
+    if cfg.api_token:
+        return cfg.api_token
+    # No token stored — prompt the user for credentials.
+    email = click.prompt("  Admin email", default=cfg.admin_email or "admin@localhost")
+    password = click.prompt(f"  Password for {email}", hide_input=True, show_default=False)
+    try:
+        resp = httpx.post(
+            f"{cfg.api_url.rstrip('/')}/api/auth/jwt/login",
+            data={"username": email, "password": password},
+            timeout=15,
+        )
+        if resp.status_code == 200:  # noqa: PLR2004
+            token = resp.json().get("access_token", "")
+            if token:
+                return token
+        error(f"Login failed (HTTP {resp.status_code})")
+        return None
+    except httpx.HTTPError as exc:
+        error(f"Could not reach backend: {exc}")
+        return None
+
+
+@click.group("observe")
+def observe_group() -> None:
+    """Observability commands — cost tracking and analytics."""
+
+
+@observe_group.command("force-calculate")
+@click.option(
+    "-y", "--yes",
+    is_flag=True,
+    help="Skip confirmation prompt.",
+)
+def force_calculate_cmd(*, yes: bool) -> None:
+    """Force-recalculate costs for all historical LLM requests.
+
+    Re-applies the current price catalog to every row in the request
+    log.  Rows with a matching model in the price catalog get updated
+    cost estimates; rows without a match are marked as unavailable.
+    """
+    cfg = load_config()
+
+    if not yes:
+        click.confirm(
+            "This will recalculate cost estimates for ALL historical requests "
+            "using the current price catalog. Continue?",
+            abort=True,
+        )
+
+    info("Authenticating…")
+    token = _ensure_token(cfg)
+    if not token:
+        error("Authentication failed. Cannot proceed.")
+        sys.exit(1)
+
+    # Temporarily set the token for this session.
+    cfg.api_token = token
+
+    with ApiClient(cfg) as client:
+        if not client.healthy():
+            error("Backend is not reachable. Is Fadenstack running?")
+            sys.exit(1)
+
+        info("Recalculating costs — this may take a moment…")
+
+        with console.status("[info]Recalculating…[/info]"):
+            resp = client.post("/api/admin/observability/recalculate-costs")
+
+        if resp.status_code != 200:  # noqa: PLR2004
+            error(f"Recalculation failed (HTTP {resp.status_code}): {resp.text}")
+            sys.exit(1)
+
+        result = resp.json()
+        recalculated = result.get("recalculated", 0)
+        unavailable = result.get("unavailable", 0)
+
+        success("Cost recalculation complete.")
+        console.print(f"  [green]{recalculated}[/green] requests updated with current pricing")
+        console.print(f"  [yellow]{unavailable}[/yellow] requests have no matching price catalog entry")