fadenstack 0.4.2__py3-none-any.whl

faden_cli/core/tune.py

@@ -0,0 +1,154 @@
+"""Size the services for this host and write it to ``.env``.
+
+The one place that does it: ``faden tune`` calls it, and so do ``deploy``,
+``upgrade`` and ``up --gen-env``. Deploy had its own copy -- the sizing baked
+into a newly generated ``.env`` -- so an existing install was never sized
+again, and a fix to the sizing reached no one who had deployed already.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.table import Table
+
+from faden_cli.core.console import console, success
+from faden_cli.core.env_gen import read_env_file, write_env_file
+from faden_cli.core.sysinfo import (
+    ALL_SERVICES,
+    DB_SERVICES,
+    DEFAULT_RESOURCE_PCT,
+    RABBIT_SERVICES,
+    TuneProfile,
+    calculate_tune_profile,
+    detect_system,
+)
+
+#: The CPU share ``faden tune --resource-pct`` accepts.
+_PCT_MIN, _PCT_MAX = 0.1, 1.0
+
+
+def _profile_of(env: dict[str, str]) -> str:
+    """The profile the install was tuned with, else the one its services run in."""
+    if env.get("FADEN_TUNE_PROFILE") in {"dev", "prod"}:
+        return env["FADEN_TUNE_PROFILE"]
+    return "dev" if env.get("FADEN_BACKEND_ENVIRONMENT") == "dev" else "prod"
+
+
+#: The flag in ``.env`` that switches each optional module on.
+_MODULE_FLAGS = {
+    "pii": "FADEN_BACKEND_PII_ENABLED",
+    "mcp": "FADEN_BACKEND_MCP_ENABLED",
+    "skills": "FADEN_BACKEND_SKILLS_ENABLED",
+}
+
+
+def _modules_of(env: dict[str, str]) -> frozenset[str]:
+    """The optional modules the install has switched on."""
+    return frozenset(m for m, flag in _MODULE_FLAGS.items() if env.get(flag, "").strip().lower() == "true")
+
+
+def _resource_pct_of(env: dict[str, str]) -> float:
+    try:
+        pct = float(env.get("FADEN_TUNE_RESOURCE_PCT") or DEFAULT_RESOURCE_PCT)
+    except ValueError:
+        return DEFAULT_RESOURCE_PCT
+    return pct if _PCT_MIN <= pct <= _PCT_MAX else DEFAULT_RESOURCE_PCT
+
+
+def tune_env(
+    env_path: Path,
+    *,
+    profile: str | None = None,
+    resource_pct: float | None = None,
+    dry_run: bool = False,
+) -> TuneProfile:
+    """Size the services for this host, show it, and write it to *env_path*.
+
+    *profile* and *resource_pct* default to what the install was last tuned
+    with, so deploy and upgrade keep what ``faden tune`` chose. The rest of
+    the file -- secrets included -- is kept.
+    """
+    env = read_env_file(env_path)
+    profile = profile or _profile_of(env)
+    resource_pct = resource_pct or _resource_pct_of(env)
+    tp = calculate_tune_profile(
+        profile, system=detect_system(), resource_pct=resource_pct, modules=_modules_of(env),
+    )
+    show(tp)
+    if dry_run:
+        console.print("[dim]Dry run — no files written.[/dim]")
+        return tp
+    env.update(tp.to_env_dict())
+    write_env_file(env_path, env, preserve_secrets=True)
+    success(f"Scalability settings written to {env_path}")
+    return tp
+
+
+def show(tp: TuneProfile) -> None:
+    """The host, the settings for each service, and the database connections they add up to."""
+    sys_info = tp.system
+    hw_table = Table(title="Detected Hardware", show_header=False, title_style="bold cyan")
+    hw_table.add_column("Metric", style="dim")
+    hw_table.add_column("Value", style="bold")
+    hw_table.add_row("Physical CPU cores", str(sys_info.physical_cores))
+    hw_table.add_row("Logical CPU cores", str(sys_info.logical_cores))
+    hw_table.add_row("Total RAM", f"{sys_info.total_ram_gb} GB")
+    hw_table.add_row("Profile", tp.profile)
+    if tp.profile == "prod":
+        hw_table.add_row("Resource budget", f"{int(tp.resource_pct * 100)}% ({tp.budget_cores} cores)")
+    console.print(hw_table)
+    console.print()
+
+    svc_table = Table(title="Computed Scalability Settings", title_style="bold cyan")
+    svc_table.add_column("Service", style="bold")
+    svc_table.add_column("Workers", justify="right")
+    svc_table.add_column("DB Pool", justify="right")
+    svc_table.add_column("DB Overflow", justify="right")
+    svc_table.add_column("RMQ Pool", justify="right")
+    svc_table.add_column("RMQ Channels", justify="right")
+    for svc in ALL_SERVICES:
+        svc_table.add_row(
+            svc,
+            str(tp.workers[svc]),
+            str(tp.db_pool_size[svc]) if svc in DB_SERVICES else "—",
+            str(tp.db_max_overflow[svc]) if svc in DB_SERVICES else "—",
+            str(tp.rabbit_pool_size[svc]) if svc in RABBIT_SERVICES else "—",
+            str(tp.rabbit_channel_pool_size[svc]) if svc in RABBIT_SERVICES else "—",
+        )
+    console.print(svc_table)
+
+    peaks = tp.db_connections()
+    console.print(
+        f"Database connections at peak: {sum(peaks.values())} "
+        f"({', '.join(f'{name} {n}' for name, n in peaks.items())}); "
+        f"Postgres max_connections {tp.max_connections}."
+    )
+    console.print()
+    show_memory(tp)
+
+
+def show_memory(tp: TuneProfile) -> None:
+    """What the sizing takes of the memory, and whether the host has it."""
+    parts = tp.memory_mb()
+    mem_table = Table(title="Memory (estimate)", show_header=False, title_style="bold cyan")
+    mem_table.add_column("Part", style="dim")
+    mem_table.add_column("MB", justify="right")
+    for name, mb in parts.items():
+        mem_table.add_row(name, str(mb))
+    mem_table.add_row("[bold]total[/bold]", f"[bold]{sum(parts.values())}[/bold]")
+    mem_table.add_row("available to Fadenstack", str(tp.memory_budget_mb))
+    console.print(mem_table)
+    workers = max(tp.workers.values())
+    if workers < tp.cpu_workers:
+        console.print(
+            f"[yellow]Workers cut from {tp.cpu_workers} to {workers} to fit "
+            f"{tp.system.total_ram_gb} GB of memory.[/yellow]"
+        )
+    if tp.memory_short_mb:
+        console.print(
+            f"[bold red]This host is {tp.memory_short_mb} MB short of memory for what is switched on.[/bold red] "
+            f"Expect swapping, and processes killed when a model downloads. Give it more memory, "
+            f"or switch modules off (faden module disable ...)."
+        )
+    console.print()

faden_cli/core/update_check.py

@@ -0,0 +1,254 @@
+"""Telling the operator, from the CLI, that a newer Fadenstack release is out.
+
+The way gh and pip do it: every command reads what the last check found
+(``update-check.json`` next to faden.yaml); when that is a day old, a thread
+fetches the release feed (release_feed.FEED_URL) while the command runs, and
+the command ends with one line on stderr if a newer release exists. A
+command never waits for the network beyond a moment at its end, and an
+offline server just hears nothing.
+
+Fetching the feed sends nothing about this server: it is a plain GET of a
+public file, compared here. Off with ``update_check: false`` in faden.yaml
+(``faden deploy`` asks) or FADEN_NO_UPDATE_CHECK=1; never in CI or when
+stderr is not a terminal (timers, scripts).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import threading
+import time
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from faden_cli import __version__
+from faden_cli.core import release_feed
+
+if TYPE_CHECKING:
+    import click
+
+    from faden_cli.core.settings import FadenConfig
+
+CACHE_NAME = "update-check.json"
+#: How old the last check may be before the next.
+STALE = timedelta(hours=24)
+FETCH_TIMEOUT_S = 3.0
+#: The most a command waits at its end for a check it started.
+JOIN_BUDGET_S = 1.5
+ENV_OFF = "FADEN_NO_UPDATE_CHECK"
+#: Commands that say more themselves (version, doctor, upgrade) or are not about an install (dev).
+QUIET_COMMANDS = frozenset({"upgrade", "version", "doctor", "dev"})
+USER_AGENT = "fadenstack-update-check"
+
+
+def installer() -> str:
+    """How this CLI was installed: pipx, uv, pip, binary, or source (a checkout)."""
+    if getattr(sys, "frozen", False):
+        return "binary"
+    prefix = Path(sys.prefix).as_posix().lower()
+    if "/pipx/" in prefix:
+        return "pipx"
+    if "/uv/tools/" in prefix:
+        return "uv"
+    if (Path(__file__).resolve().parents[3] / "pyproject.toml").is_file():
+        return "source"
+    return "pip"
+
+
+def upgrade_kind(cfg: FadenConfig) -> str:
+    """How the install this CLI looks after moves to a new release: like the console says it.
+
+    An install built from a checkout gets a release by ``git pull`` (``source``), however
+    the CLI itself was installed; any other by a newer CLI, the way this one was installed.
+    """
+    if cfg.install_dir and current_release(cfg) is None:
+        from faden_cli.core.installation import checkout_of  # noqa: PLC0415
+
+        try:
+            if checkout_of(cfg.install_path) is not None:
+                return "source"
+        except OSError:
+            pass
+    return installer()
+
+
+def enabled(cfg: FadenConfig) -> bool:
+    """Whether this CLI checks for releases at all."""
+    if os.environ.get(ENV_OFF, "").strip().lower() not in ("", "0", "false", "no"):
+        return False
+    return bool(cfg.update_check)
+
+
+def cache_path() -> Path:
+    """Where the last check is kept: beside faden.yaml."""
+    from faden_cli.core.settings import config_path  # noqa: PLC0415
+
+    return config_path().parent / CACHE_NAME
+
+
+def feed_url(cfg: FadenConfig) -> str:
+    """The feed this CLI reads: the configured mirror, else fadenstack.com."""
+    return (cfg.update_feed_url or "").strip() or release_feed.FEED_URL
+
+
+def _read_cache() -> dict[str, Any]:
+    try:
+        data = json.loads(cache_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    path = cache_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data), encoding="utf-8")
+        tmp.replace(path)
+    except OSError:
+        pass  # a read-only home: the check runs again next time
+
+
+def _checked_at(data: dict[str, Any]) -> datetime | None:
+    try:
+        return datetime.fromisoformat(str(data["checked_at"]))
+    except (KeyError, ValueError):
+        return None
+
+
+def is_stale(now: datetime | None = None) -> bool:
+    """Whether the last check (or failed attempt) is older than :data:`STALE`."""
+    checked = _checked_at(_read_cache())
+    return checked is None or (now or datetime.now(UTC)) - checked >= STALE
+
+
+def cached_feed() -> release_feed.Feed | None:
+    """The feed the last successful check kept, verified again; None if there is none."""
+    data = _read_cache()
+    try:
+        return release_feed.verify(data["index"].encode(), data["signature"].encode())
+    except (KeyError, AttributeError, release_feed.FeedError):
+        return None
+
+
+def fetch(url: str, *, timeout: float = FETCH_TIMEOUT_S) -> tuple[bytes, bytes]:
+    """The feed and its signature, as published at *url*."""
+    import httpx  # noqa: PLC0415
+
+    with httpx.Client(timeout=timeout, follow_redirects=True, headers={"User-Agent": USER_AGENT}) as client:
+        index = client.get(url)
+        index.raise_for_status()
+        signature = client.get(release_feed.signature_url(url))
+        signature.raise_for_status()
+    return index.content, signature.content
+
+
+def refresh(cfg: FadenConfig, *, timeout: float = FETCH_TIMEOUT_S) -> release_feed.Feed:
+    """Fetch and verify the feed now, and keep it. Raises on failure (and remembers the attempt)."""
+    previous = _read_cache()
+    now = datetime.now(UTC)
+    try:
+        index, signature = fetch(feed_url(cfg), timeout=timeout)
+        feed = release_feed.verify(index, signature)
+        seen = cached_feed()
+        release_feed.not_older(feed, seen.generated_at if seen else None)
+    except Exception as exc:
+        # Tried: the next try waits a day too, so an offline server is not asked on every command.
+        _write_cache({**previous, "checked_at": now.isoformat(), "error": str(exc) or type(exc).__name__})
+        raise
+    _write_cache({
+        "checked_at": now.isoformat(),
+        "url": feed_url(cfg),
+        "index": index.decode(),
+        "signature": signature.decode(),
+    })
+    return feed
+
+
+def current_release(cfg: FadenConfig) -> str | None:
+    """The release the install this CLI looks after runs; None without one made from a release."""
+    if not cfg.install_dir:
+        return None
+    from faden_cli.core.bundle import installed_release  # noqa: PLC0415
+
+    try:
+        return installed_release(cfg.install_path)
+    except OSError:
+        return None
+
+
+def message(feed: release_feed.Feed, cfg: FadenConfig) -> str | None:
+    """What to tell the operator, in one or two lines; None when there is nothing to tell."""
+    installed = current_release(cfg)
+    # The CLI is already newer than the install: the step left is the upgrade itself.
+    if installed and release_feed.is_newer(__version__, installed):
+        return f"This CLI is {__version__}; the install still runs {installed}. Upgrade it: faden upgrade"
+    assessment = release_feed.assess(feed, __version__, cfg.update_channel)
+    if not assessment.update_available or assessment.latest is None:
+        if assessment.unsupported:
+            return f"Fadenstack {__version__} no longer gets fixes (since {assessment.supported_until})."
+        return None
+    urgency = {
+        "critical": " -- a critical fix: upgrade now",
+        "security": " -- it fixes security problems",
+    }.get(assessment.severity, "")
+    steps = release_feed.upgrade_commands(upgrade_kind(cfg), assessment)
+    lines = [f"Fadenstack {assessment.latest.version} is available (you have {__version__}){urgency}."]
+    if assessment.path and len(assessment.path) > 1:
+        lines.append(f"Upgrade one release at a time: {' -> '.join(assessment.path)}.")
+    if steps:
+        lines.append(f"Upgrade: {steps[0]}, then faden upgrade")
+    return "\n".join(lines)
+
+
+def interactive() -> bool:
+    """Whether someone watches stderr: a terminal, and not CI."""
+    try:
+        return sys.stderr.isatty() and not os.environ.get("CI")
+    except (AttributeError, ValueError):
+        return False
+
+
+def start(ctx: click.Context, *, quiet: bool) -> None:
+    """Check in the background while the command runs, and tell the operator at its end."""
+    command = ctx.invoked_subcommand
+    if quiet or command is None or command in QUIET_COMMANDS or not interactive():
+        return
+    from faden_cli.core.settings import load_config  # noqa: PLC0415
+
+    try:
+        cfg = load_config()
+    except Exception:  # a broken faden.yaml is the command's to report
+        return
+    if not enabled(cfg):
+        return
+    started = time.monotonic()
+    worker: threading.Thread | None = None
+    if is_stale():
+        worker = threading.Thread(
+            target=_refresh_quietly, args=(cfg,), name="faden-update-check", daemon=True
+        )
+        worker.start()
+
+    def tell() -> None:
+        if worker is not None:
+            worker.join(max(0.0, JOIN_BUDGET_S - (time.monotonic() - started)))
+        feed = cached_feed()
+        text = message(feed, cfg) if feed is not None else None
+        if text:
+            from rich.console import Console  # noqa: PLC0415
+
+            Console(stderr=True).print(f"\n[yellow]{text}[/yellow]", highlight=False)
+
+    ctx.call_on_close(tell)
+
+
+def _refresh_quietly(cfg: FadenConfig) -> None:
+    # An offline server hears nothing; the attempt is remembered.
+    with contextlib.suppress(Exception):
+        refresh(cfg)

faden_cli/core/workspace.py

@@ -0,0 +1,155 @@
+"""Shared workspace helpers for ``faden dev`` commands.
+
+``dev init`` clones the Fadenstack repos as a *monorepo* at
+``<workspace>/fadenstack/<local_name>``.  Consumers (``dev up``,
+``dev status``, …) must resolve service paths the same way, which is
+why the helpers live here instead of being duplicated per command.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+CORE_DIRNAME = "fadenstack"
+
+# Well-known Fadenstack dev processes and the log files they write to in
+# headless (no terminal-emulator) mode.
+LOG_LABELS = {
+    "backend": "faden-backend.log",
+    "worker": "faden-taskiq-worker.log",
+    "frontend": "faden-frontend.log",
+    "gateway": "faden-gateway.log",
+}
+
+
+def find_service_dir(workspace: Path, name: str) -> Path:
+    """Return the path to a service directory, checking the monorepo first.
+
+    ``faden dev init`` clones everything under
+    ``<workspace>/fadenstack/<name>``.  Legacy/flat layouts that keep
+    the service directly in ``<workspace>/<name>`` still work.
+    """
+    monorepo = workspace / CORE_DIRNAME / name
+    if monorepo.is_dir():
+        return monorepo
+    return workspace / name
+
+
+#: A directory counts as a workspace when these services resolve beneath it,
+#: in either layout ``find_service_dir`` understands.  Backend + shared are
+#: enough to tell a real checkout from a directory that merely has a similar
+#: name: the first is the service ``dev up`` launches, the second holds the
+#: compose file and the ``.env`` everything else is derived from.
+WORKSPACE_MARKERS = ("backend", "shared")
+
+
+def is_workspace(path: Path) -> bool:
+    """True when *path* already holds a Fadenstack checkout."""
+    return all(find_service_dir(path, name).is_dir() for name in WORKSPACE_MARKERS)
+
+
+def detect_workspace(start: Path | None = None) -> Path | None:
+    """Find the nearest workspace root at or above *start* (default: cwd).
+
+    This is what lets a developer who cloned the code themselves skip
+    ``dev init``'s clone step: the commands find the checkout instead of
+    requiring config written by a previous ``dev init``.
+
+    Searching upwards matters because the directory a developer is standing
+    in is usually a service, not the workspace root.  The *nearest* match
+    wins, so a nested monorepo checkout resolves to itself rather than to
+    some unrelated ancestor.  Returns ``None`` when nothing above *start*
+    looks like a checkout, so callers keep their previous behaviour.
+    """
+    origin = (start or Path.cwd()).resolve()
+    for candidate in (origin, *origin.parents):
+        if is_workspace(candidate):
+            return candidate
+    return None
+
+
+def resolve_workspace(*, remember: bool = False) -> Path:
+    """The workspace the ``dev`` commands should act on.
+
+    One implementation for ``up`` / ``down`` / ``status``, which previously
+    each resolved this themselves and would drift apart the moment one of
+    them learned something the others did not.
+
+    Order: the configured workspace when it holds a checkout, then detection
+    from the cwd, then the configured path (or cwd) unchanged so a caller
+    still fails the way it used to rather than in some new way.
+
+    ``remember`` persists a detected workspace to config, so the commands
+    that only read it agree with the one that found it.
+    """
+    from faden_cli.core.console import info, warning
+    from faden_cli.core.settings import load_config
+
+    cfg = load_config()
+    configured = Path(cfg.dev.workspace_dir) if cfg.dev and cfg.dev.workspace_dir else None
+    if configured and is_workspace(configured):
+        return configured
+
+    detected = detect_workspace()
+    if detected:
+        if configured:
+            warning(f"Configured workspace {configured} holds no checkout — using {detected}")
+        else:
+            info(f"Detected workspace at {detected}")
+        if remember:
+            _remember_workspace(detected)
+        return detected
+
+    return configured or Path.cwd()
+
+
+def _remember_workspace(workspace: Path) -> None:
+    """Persist a detected workspace so the read-only dev commands agree."""
+    from faden_cli.core.console import warning
+    from faden_cli.core.settings import DevConfig, load_config, save_config
+
+    cfg = load_config()
+    if cfg.dev and cfg.dev.workspace_dir == str(workspace):
+        return
+    cfg.dev = cfg.dev or DevConfig()
+    cfg.dev.workspace_dir = str(workspace)
+    try:
+        save_config(cfg)
+    except OSError as exc:  # noqa: BLE001 — a read-only config must not stop a dev run
+        warning(f"Could not save the detected workspace to config: {exc}")
+
+
+def resolve_shared_compose(workspace: Path) -> Path | None:
+    """Locate the shared docker-compose file for a dev workspace."""
+    for candidate in (
+        workspace / "shared" / "docker-compose.yaml",
+        workspace / "shared" / "docker-compose.yml",
+        workspace / CORE_DIRNAME / "shared" / "docker-compose.yaml",
+        workspace / CORE_DIRNAME / "shared" / "docker-compose.yml",
+        workspace / "infra" / "shared" / "docker-compose.yaml",
+        workspace / "infra" / "shared" / "docker-compose.yml",
+    ):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def log_filename(label: str) -> str:
+    """Log file name for a dev process label (``backend``/``worker``/...).
+
+    Unmapped labels are slugified rather than interpolated raw. A label with a
+    space fell through this fallback and produced ``faden-api gateway.log`` -- a
+    space in a path every caller then has to quote, and which nothing in the
+    tooling did.
+    """
+    known = LOG_LABELS.get(label)
+    if known is not None:
+        return known
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", label).strip("-").lower() or "process"
+    return f"faden-{slug}.log"
+
+
+def dev_logs_dir() -> Path:
+    """Directory holding background (headless) dev process log files."""
+    return Path.home() / ".faden-dev" / "logs"

faden_cli/templates/env.j2

@@ -0,0 +1,33 @@
+# ─────────────────────────────────────────────────────────────────
+#  Fadenstack — Environment Configuration
+#  Generated by faden CLI v{{ version }}  •  {{ timestamp }}
+# ─────────────────────────────────────────────────────────────────
+
+# ── Postgres ──────────────────────────────────────────────────────
+POSTGRES_USER={{ postgres_user }}
+POSTGRES_PASSWORD={{ postgres_password }}
+POSTGRES_DB={{ postgres_db }}
+
+# ── Redis ─────────────────────────────────────────────────────────
+REDIS_PASSWORD={{ redis_password }}
+
+# ── RabbitMQ ──────────────────────────────────────────────────────
+RABBITMQ_DEFAULT_USER={{ rabbitmq_user }}
+RABBITMQ_DEFAULT_PASS={{ rabbitmq_password }}
+
+# ── MinIO (S3-compatible object storage) ──────────────────────────
+MINIO_ROOT_USER={{ minio_root_user }}
+MINIO_ROOT_PASSWORD={{ minio_root_password }}
+
+# ── Langfuse (LLM observability) ─────────────────────────────────
+LANGFUSE_SECRET_KEY={{ langfuse_secret_key }}
+LANGFUSE_NEXT_AUTH_SECRET={{ langfuse_next_auth_secret }}
+LANGFUSE_SALT={{ langfuse_salt }}
+
+# ── JWT ───────────────────────────────────────────────────────────
+JWT_SECRET={{ jwt_secret }}
+
+# ── Module flags ──────────────────────────────────────────────────
+{% for key, value in module_vars.items() -%}
+{{ key }}={{ value }}
+{% endfor %}

faden_cli/tui/__init__.py

@@ -0,0 +1 @@
+"""TUI components built on Textual."""

faden_cli/tui/widgets/__init__.py

@@ -0,0 +1 @@
+"""Custom Textual widgets for the faden TUI."""

faden_cli/tui/wizard/__init__.py

@@ -0,0 +1 @@
+"""Init wizard screens for the Textual TUI."""