fadenstack 0.4.2__py3-none-any.whl

faden_cli/commands/ports.py

@@ -0,0 +1,91 @@
+"""``faden ports`` — the host ports the console, the API and /v1 are served on."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from faden_cli.core.console import console, error, success, warning
+from faden_cli.core.edge import HTTP_PORT_KEY, HTTPS_PORT_KEY, check_ports, ports
+from faden_cli.core.env_gen import read_env_file, write_env_file
+from faden_cli.core.settings import load_config
+
+
+def port_conflicts(http: int, https: int, *, current: tuple[int, int]) -> list[str]:
+    """Which of the wanted ports something other than this install holds."""
+    from faden_cli.core.detect import _ports_held_by_faden, check_port  # noqa: PLC0415
+
+    ours = _ports_held_by_faden()
+    problems = []
+    for label, port in (("HTTP", http), ("HTTPS", https)):
+        if port in current or port in ours:
+            continue
+        if check_port(port).in_use:
+            problems.append(f"{label} port {port} is in use by something else.")
+    return problems
+
+
+def set_ports(env_path: Path, *, http: int | None, https: int | None) -> tuple[int, int] | None:
+    """Write the wanted ports into *env_path*; the new pair, or ``None`` when nothing changed."""
+    env = read_env_file(env_path)
+    current = ports(env)
+    wanted = (http if http is not None else current[0], https if https is not None else current[1])
+    if wanted == current:
+        return None
+    problem = check_ports(*wanted)
+    if problem:
+        raise click.UsageError(problem)
+    env[HTTP_PORT_KEY] = str(wanted[0])
+    env[HTTPS_PORT_KEY] = str(wanted[1])
+    write_env_file(env_path, env)
+    return wanted
+
+
+@click.command("ports")
+@click.option("--http", "http", type=int, default=None, help="Host port for plain HTTP (default 80).")
+@click.option("--https", "https", type=int, default=None, help="Host port for HTTPS (default 443).")
+@click.option(
+    "--no-restart", is_flag=True, help="Write .env only; the proxy moves when it is next recreated."
+)
+def ports_cmd(*, http: int | None, https: int | None, no_restart: bool) -> None:
+    """Show or change the ports the console, the API and /v1 are served on.
+
+    \b
+    faden ports                        show them
+    faden ports --http 8080 --https 8443
+    """
+    from faden_cli.commands.tls import addresses, apply_to_proxy  # noqa: PLC0415
+
+    cfg = load_config()
+    if not cfg.install_dir:
+        error("No install found. Run faden deploy first.")
+        sys.exit(1)
+    install_dir = Path(cfg.install_dir)
+    env_path = install_dir / ".env"
+    current = ports(read_env_file(env_path))
+
+    if http is None and https is None:
+        console.print(f"HTTP on port [bold]{current[0]}[/bold], HTTPS on port [bold]{current[1]}[/bold].")
+        console.print("  " + "  ".join(addresses(install_dir)))
+        return
+
+    wanted = (http if http is not None else current[0], https if https is not None else current[1])
+    problem = check_ports(*wanted)
+    if problem:
+        error(problem)
+        sys.exit(2)
+    for conflict in port_conflicts(*wanted, current=current):
+        warning(conflict + " The proxy cannot start on it until it is free.")
+
+    if set_ports(env_path, http=http, https=https) is None:
+        console.print("Nothing to change.")
+        return
+    success(f"HTTP on port {wanted[0]}, HTTPS on port {wanted[1]} (written to {env_path}).")
+    if not no_restart and not apply_to_proxy(install_dir, recreate=True):
+        sys.exit(1)
+    from faden_cli.commands.tls import refresh_edge_info  # noqa: PLC0415
+
+    refresh_edge_info(install_dir)
+    console.print("  " + "  ".join(addresses(install_dir)))

faden_cli/commands/rebuild.py

@@ -0,0 +1,158 @@
+"""``faden rebuild`` — rebuild and redeploy individual services.
+
+Rebuild one or more services without touching the rest of the stack.
+Useful for developers who changed frontend code, backend code, etc.
+and want a quick turnaround without a full ``faden deploy``.
+
+Examples:
+    faden rebuild frontend          # rebuild + restart frontend only
+    faden rebuild backend api       # rebuild backend and api
+    faden rebuild --all             # rebuild all app services
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from faden_cli.core.compose import (
+    ComposeContext,
+    build as compose_build,
+    build_context_from_config,
+    up as compose_up,
+)
+from faden_cli.core.console import console, error, info, success, warning
+from faden_cli.core.settings import load_config
+
+
+# Map friendly names → compose service names.
+# Keeps the CLI developer-friendly (``faden rebuild frontend``)
+# while resolving to the actual compose service name.
+SERVICE_ALIASES: dict[str, list[str]] = {
+    "frontend": ["faden-frontend"],
+    "backend": ["faden-backend-migrator", "faden-backend", "faden-backend-worker"],
+    "gateway": ["faden-gateway-migrator", "faden-gateway"],
+    "mcp": ["faden-mcp"],
+    "skills": ["faden-skills"],
+    "pii": ["faden-pii", "faden-pii-worker"],
+    "rag": ["faden-rag"],
+    "auth": ["faden-auth"],
+    "mailer": ["faden-mailer"],
+    "docling": ["faden-docling"],
+    "nginx": ["faden-nginx"],
+}
+
+# Services that don't have a build context (they reuse another service's image).
+# compose_build() skips these; they just need their container recreated.
+_NO_BUILD_SERVICES: frozenset[str] = frozenset({
+    "faden-backend-migrator",
+    "faden-gateway-migrator",
+})
+
+
+def _resolve_services(names: tuple[str, ...]) -> list[str]:
+    """Resolve friendly names to compose service names."""
+    resolved: list[str] = []
+    for name in names:
+        name = name.lower().strip()
+        if name in SERVICE_ALIASES:
+            resolved.extend(SERVICE_ALIASES[name])
+        elif name.startswith("faden-"):
+            resolved.append(name)
+        else:
+            # Try with prefix
+            prefixed = f"faden-{name}"
+            resolved.append(prefixed)
+    return list(dict.fromkeys(resolved))  # dedupe, preserve order
+
+
+@click.command("rebuild")
+@click.argument("services", nargs=-1)
+@click.option("--all", "rebuild_all", is_flag=True, help="Rebuild all application services.")
+@click.option("--no-cache", is_flag=True, help="Build without Docker cache.")
+@click.option("--no-deps", is_flag=True, default=True, help="Don't restart dependent services (default: true).")
+@click.option("--with-deps", is_flag=True, help="Also restart dependent services.")
+def rebuild_cmd(
+    services: tuple[str, ...],
+    *,
+    rebuild_all: bool,
+    no_cache: bool,
+    no_deps: bool,
+    with_deps: bool,
+) -> None:
+    """Rebuild and redeploy specific services.
+
+    Pass one or more service names (e.g. frontend, backend, api, mcp).
+    The service image is rebuilt from source and the container is
+    recreated with the latest .env values — no full redeploy needed.
+
+    \b
+    Examples:
+        faden rebuild frontend           # just the React UI
+        faden rebuild backend            # backend + worker
+        faden rebuild backend api        # multiple services
+        faden rebuild --all              # all app images
+        faden rebuild frontend --no-cache  # clean build
+    """
+    if not services and not rebuild_all:
+        # Show available aliases
+        console.print("[bold cyan]Available services:[/bold cyan]")
+        for alias, targets in sorted(SERVICE_ALIASES.items()):
+            console.print(f"  [bold]{alias:12s}[/bold] → {', '.join(targets)}")
+        console.print("\n[dim]Usage: faden rebuild <service> [service...][/dim]")
+        console.print("[dim]       faden rebuild --all[/dim]")
+        return
+
+    cfg = load_config()
+    ctx = build_context_from_config(cfg)
+
+    if rebuild_all:
+        # Build all services that have a build context
+        target_services = None  # compose build with no args = build all
+        info("Rebuilding all application images…")
+    else:
+        target_services = _resolve_services(services)
+        info(f"Rebuilding: {', '.join(target_services)}")
+
+    # Step 1: Build (skip migrators — they share the parent service image)
+    build_services = (
+        [s for s in target_services if s not in _NO_BUILD_SERVICES]
+        if target_services
+        else None
+    )
+    console.print("\n[bold cyan]Building images…[/bold cyan]")
+    rc = compose_build(ctx, services=build_services or None, no_cache=no_cache)
+    if rc != 0:
+        error(f"Build failed (exit code {rc}).")
+        sys.exit(rc)
+    success("Images built.")
+
+    # Step 1b: Sync Postgres password if .env credentials differ from
+    # what the running Postgres volume was initialised with (e.g. after
+    # deploy-remote.sh updated the .env or a manual edit).
+    env_path = ctx.env_file
+    if env_path and env_path.exists():
+        from faden_cli.commands.deploy import _sync_postgres_password  # noqa: PLC0415
+
+        _sync_postgres_password(ctx, env_path)
+
+    # Step 2: Recreate containers (picks up new image + new .env)
+    console.print("\n[bold cyan]Recreating containers…[/bold cyan]")
+
+    cmd = ctx.base_cmd() + ["up", "-d", "--force-recreate"]
+    if no_deps and not with_deps:
+        cmd.append("--no-deps")
+    if target_services:
+        cmd.extend(target_services)
+
+    import subprocess
+    result = subprocess.run(cmd, check=False)  # noqa: S603
+    if result.returncode != 0:
+        error(f"Container recreation failed (exit code {result.returncode}).")
+        sys.exit(result.returncode)
+
+    success("Services rebuilt and redeployed.")
+    if target_services:
+        console.print(f"  [dim]Rebuilt: {', '.join(target_services)}[/dim]")
+    console.print("  [dim]Tip: use 'faden logs <service>' to follow logs.[/dim]")

faden_cli/commands/restore.py

@@ -0,0 +1,139 @@
+"""``faden restore`` — restore from a backup directory.
+
+Examples:
+    faden restore backups/20250115T120000Z
+    faden restore backups/20250115T120000Z --verify-only
+    faden restore backups/20250115T120000Z --db-only
+    faden restore backups/20250115T120000Z --skip-env
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from faden_cli.core.backup import (
+    read_manifest,
+    restore_backup,
+    verify_backup,
+)
+from faden_cli.core.compose import (
+    build_context_from_config,
+    down as compose_down,
+    up as compose_up,
+)
+from faden_cli.core.console import console, error, info, success, warning
+from faden_cli.core.settings import load_config
+from faden_cli.commands.deploy import _sync_postgres_password
+
+
+@click.command("restore")
+@click.argument("backup_dir", type=click.Path(exists=True, file_okay=False))
+@click.option("--db-only", is_flag=True, default=False, help="Restore databases only.")
+@click.option("--skip-env", is_flag=True, default=False, help="Don't overwrite the current .env.")
+@click.option(
+    "--verify-only",
+    is_flag=True,
+    default=False,
+    help="Validate checksums without restoring.",
+)
+@click.option("-y", "--yes", is_flag=True, default=False, help="Skip confirmation prompt.")
+def restore_cmd(
+    backup_dir: str,
+    *,
+    db_only: bool,
+    skip_env: bool,
+    verify_only: bool,
+    yes: bool,
+) -> None:
+    """Restore Fadenstack from a backup directory.
+
+    BACKUP_DIR is the path to a timestamped backup folder containing
+    a manifest.json file created by ``faden backup``.
+    """
+    console.print("\n[bold magenta]fadenstack — Restore[/bold magenta]\n")
+
+    backup_path = Path(backup_dir).resolve()
+    manifest = read_manifest(backup_path)
+    if manifest is None:
+        error(f"No manifest.json found in {backup_path}")
+        sys.exit(1)
+
+    # ── Show backup info ──────────────────────────────────────
+    console.print(f"  Backup date:    {manifest.get('created_at', 'unknown')}")
+    console.print(f"  faden version: {manifest.get('faden_version', 'unknown')}")
+    db_names = list(manifest.get("databases", {}).keys())
+    console.print(f"  Databases:      {', '.join(db_names)}")
+    if manifest.get("env_snapshot"):
+        console.print(f"  .env snapshot:  {manifest['env_snapshot']}")
+    if manifest.get("volumes"):
+        console.print(f"  Volumes:        {', '.join(manifest['volumes'])}")
+    console.print()
+
+    # ── Verify checksums ──────────────────────────────────────
+    info("Verifying backup checksums…")
+    check_errors = verify_backup(backup_path, manifest)
+    if check_errors:
+        for msg in check_errors:
+            error(f"  {msg}")
+        sys.exit(1)
+    success("Checksums OK.")
+
+    if verify_only:
+        return
+
+    # ── Confirm ───────────────────────────────────────────────
+    if not yes:
+        console.print()
+        warning("This will overwrite current databases with the backup data.")
+        click.confirm("Proceed with restore?", default=False, abort=True)
+
+    cfg = load_config()
+    ctx = build_context_from_config(cfg)
+
+    # ── Stop application services (keep postgres) ─────────────
+    console.print("\n[bold cyan]Stopping application services…[/bold cyan]")
+    compose_down(ctx, remove_orphans=False)
+    # Bring postgres back up for the restore
+    compose_up(ctx, services=["postgres"], detach=True, wait=True, timeout=60)
+
+    # ── Restore ───────────────────────────────────────────────
+    result = restore_backup(
+        ctx,
+        backup_dir=backup_path,
+        db_only=db_only,
+        skip_env=skip_env,
+    )
+
+    if not result.ok:
+        for msg in result.errors:
+            error(msg)
+        sys.exit(1)
+
+    # ── Sync Postgres password with restored .env ─────────────
+    if result.env_restored:
+        env_path = ctx.env_file or Path(ctx.project_dir) / ".env"
+        # A .env backed up before a release required it may lack a key the compose file now requires.
+        from faden_cli.core.env_gen import fill_required_env  # noqa: PLC0415
+
+        for note in fill_required_env(env_path, profiles=list(cfg.profiles)):
+            warning(note)
+        info("Syncing Postgres password with restored .env…")
+        _sync_postgres_password(ctx, env_path)
+
+    # ── Restart all services ──────────────────────────────────
+    console.print("\n[bold cyan]Restarting all services…[/bold cyan]")
+    compose_up(ctx, detach=True, wait=True, timeout=120)
+
+    console.print()
+    success("Restore complete.")
+    if result.databases_restored:
+        console.print(f"  Databases: {', '.join(result.databases_restored)}")
+    if result.env_restored:
+        console.print("  .env: restored")
+    if result.volumes_restored:
+        console.print(f"  Volumes: {', '.join(result.volumes_restored)}")
+    if result.tls_restored:
+        console.print(f"  Certificate material: {len(result.tls_restored)} file(s); the machines still trust it")

faden_cli/commands/runtime_images.py

@@ -0,0 +1,174 @@
+"""``faden runtime-images``: the runtime images this server holds for its machines.
+
+The same step runs at the end of ``deploy`` and ``upgrade``; this command runs
+it on its own -- to retry a pull that failed, to fetch an architecture chosen
+later, or (``--check``) to see what is here.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.table import Table
+
+from faden_cli.core import runtime_images as rt
+from faden_cli.core.console import console, info, success, warning
+from faden_cli.core.settings import FadenConfig, load_config, save_config
+
+_HOW_TO_RETRY = "faden runtime-images"
+
+
+def choose(cfg: FadenConfig, value: str | None) -> set[str] | None:
+    """The architectures to fetch: *value* when given (and remembered), else the saved choice.
+
+    Returns None, after saying why, when *value* is not a valid choice.
+    """
+    try:
+        chosen = rt.parse_selection(value if value is not None else cfg.runtime_images)
+    except ValueError as exc:
+        warning(f"--runtime-images: {exc}")
+        return None
+    if value is not None and value != cfg.runtime_images:
+        cfg.runtime_images = value
+        save_config(cfg)
+    return chosen
+
+
+def run_step(cfg: FadenConfig, *, value: str | None = None) -> bool:
+    """Fetch this release's runtime images onto the server and say what happened.
+
+    Never stops the caller: every service is already running without them,
+    and a machine can still be served by a cluster peer that has its image.
+    Returns whether everything wanted is here.
+    """
+    chosen = choose(cfg, value)
+    if chosen is None:
+        return False
+    if not chosen:
+        console.print("  [dim]Skipping runtime images (runtime_images: none).[/dim]")
+        return True
+
+    image = rt.backend_image(cfg.env_path)
+    info(f"Runtime images pinned by {image} ({', '.join(sorted(chosen))}):")
+    console.print(
+        "  [dim]Machines download their runtime image from this server. The first pull is large"
+        " (about 10 GB per image); later upgrades fetch only what changed.[/dim]"
+    )
+    try:
+        report = rt.fetch(image, architectures=chosen)
+    except RuntimeError as exc:  # docker missing
+        warning(f"Could not fetch runtime images: {exc}")
+        return False
+    if report.error:
+        warning(f"Could not fetch runtime images: {report.error}")
+        return False
+
+    for outcome in report.outcomes:
+        _say(outcome)
+    return _model_tls_images(chosen) and report.ok
+
+
+def _model_tls_images(chosen: set[str]) -> bool:
+    """The machines' model-TLS proxy (nginx), per architecture: small, and needed by air-gapped machines."""
+    info("Model-TLS proxy image for the machines (nginx):")
+    try:
+        outcomes = rt.fetch_model_tls(chosen)
+    except RuntimeError as exc:
+        warning(f"Could not fetch the model-TLS proxy image: {exc}")
+        return False
+    ok = True
+    for tag, arch, outcome in outcomes:
+        what = f"{tag} ({arch})"
+        if outcome == "present":
+            success(f"{what}: already on this server.")
+        elif outcome == "pulled":
+            success(f"{what}: pulled.")
+        elif outcome == "skipped":
+            console.print(f"  [dim]{what}: skipped, not chosen (--runtime-images).[/dim]")
+        else:
+            ok = False
+            reason = "docker pull failed"
+            if outcome == "mismatch":
+                reason = "the registry's image is not the pinned build"
+            warning(
+                f"{what}: {reason}. Machines with internet access pull it themselves;"
+                f" retry with {_HOW_TO_RETRY}."
+            )
+    return ok
+
+
+def _say(outcome: rt.Outcome) -> None:
+    """One line (or two) per image, in the operator's terms."""
+    what = f"{outcome.image.ref} ({outcome.image.arch or 'any architecture'})"
+    if outcome.status == "present":
+        success(f"{what}: already on this server.")
+    elif outcome.status == "pulled":
+        success(f"{what}: pulled.")
+    elif outcome.status == "skipped":
+        console.print(f"  [dim]{what}: skipped, not chosen (--runtime-images).[/dim]")
+    elif outcome.status == "not_published":
+        warning(
+            f"{what}: this release names a build that is on no registry.\n"
+            "  Machines of this kind can get it from a cluster peer that has it;"
+            " or load it here with: docker load -i <file>"
+        )
+    elif outcome.status == "mismatch":
+        warning(f"{what}: {outcome.detail}; machines would refuse it.")
+    else:
+        warning(
+            f"{what}: pull failed. Retry with: {_HOW_TO_RETRY}\n"
+            "  If the registry refused it: the package must be public, or run docker login ghcr.io first."
+        )
+
+
+def _check(cfg: FadenConfig) -> bool:
+    image = rt.backend_image(cfg.env_path)
+    try:
+        pinned = rt.pinned(image)
+    except RuntimeError as exc:
+        warning(str(exc))
+        return False
+    table = Table(title=f"Runtime images pinned by {image}", header_style="bold cyan")
+    table.add_column("Architecture")
+    table.add_column("Image")
+    table.add_column("On this server")
+    everything = True
+    for runtime in pinned:
+        here = rt.local_layers(runtime.ref)
+        if here is None:
+            state = "[yellow]no[/yellow]"
+            everything = False
+        elif here == runtime.rootfs_layers:
+            state = "[green]yes[/green]"
+        else:
+            state = "[red]a different build[/red]"
+            everything = False
+        table.add_row(runtime.arch or "-", runtime.ref, state)
+    console.print(table)
+    return everything
+
+
+@click.command("runtime-images")
+@click.option(
+    "--arch",
+    "arch",
+    default=None,
+    help="Which to fetch: all, none, or architectures such as x86_64,aarch64 (remembered for upgrades).",
+)
+@click.option("--check", is_flag=True, default=False, help="Only show what this server holds; fetch nothing.")
+def runtime_images_cmd(*, arch: str | None, check: bool) -> None:
+    r"""Fetch the runtime images machines download from this server.
+
+    \b
+    Examples:
+        faden runtime-images                 # fetch what this release pins
+        faden runtime-images --arch x86_64   # only for x86_64 machines, from now on
+        faden runtime-images --check         # what is here, what is missing
+    """
+    cfg = load_config()
+    if not cfg.install_dir:
+        warning("No install directory configured. Run 'faden deploy' first.")
+        sys.exit(1)
+    ok = _check(cfg) if check else run_step(cfg, value=arch)
+    sys.exit(0 if ok else 1)

faden_cli/commands/status.py

@@ -0,0 +1,71 @@
+"""``faden status`` — show running service status."""
+
+from __future__ import annotations
+
+import click
+from rich.table import Table
+
+from faden_cli.core.compose import build_context_from_config, ps as compose_ps
+from faden_cli.core.console import console
+from faden_cli.core.settings import load_config
+
+
+def _health_style(health: str) -> str:
+    mapping = {
+        "healthy": "[green]healthy[/green]",
+        "unhealthy": "[red]unhealthy[/red]",
+        "starting": "[yellow]starting[/yellow]",
+    }
+    return mapping.get(health.lower(), health) if health else "—"
+
+
+def _state_style(state: str) -> str:
+    mapping = {
+        "running": "[green]running[/green]",
+        "exited": "[red]exited[/red]",
+        "restarting": "[yellow]restarting[/yellow]",
+        "created": "[dim]created[/dim]",
+        "dead": "[red]dead[/red]",
+    }
+    return mapping.get(state.lower(), state) if state else "—"
+
+
+@click.command("status")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON from docker compose.")
+def status_cmd(*, as_json: bool) -> None:
+    """Show the status of Fadenstack services."""
+    cfg = load_config()
+    ctx = build_context_from_config(cfg)
+
+    services = compose_ps(ctx)
+
+    if as_json:
+        import json
+
+        click.echo(json.dumps([s.__dict__ for s in services], indent=2))
+        return
+
+    if not services:
+        console.print("[dim]No running services found.[/dim]")
+        return
+
+    table = Table(
+        title="Fadenstack Services",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Service", style="bold")
+    table.add_column("State")
+    table.add_column("Health")
+    table.add_column("Ports")
+
+    for svc in sorted(services, key=lambda s: s.service):
+        table.add_row(
+            svc.service,
+            _state_style(svc.state),
+            _health_style(svc.health),
+            svc.ports or "—",
+        )
+
+    console.print(table)
+    console.print(f"\n[dim]{len(services)} service(s)[/dim]")