fadenstack 0.4.2__py3-none-any.whl

faden_cli/cli.py

@@ -0,0 +1,158 @@
+"""CLI entry point — Click root group and subcommand registration.
+
+This module defines the ``faden`` command group and wires up all
+subcommands.  Run ``faden --help`` for the full command tree.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from faden_cli import __version__
+
+
+class AliasedGroup(click.Group):
+    """Click group that supports command abbreviations.
+
+    For instance ``faden st`` resolves to ``faden status`` if no
+    other command starts with ``st``.
+    """
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        rv = click.Group.get_command(self, ctx, cmd_name)
+        if rv is not None:
+            return rv
+        matches = [x for x in self.list_commands(ctx) if x.startswith(cmd_name)]
+        if not matches:
+            return None
+        if len(matches) == 1:
+            return click.Group.get_command(self, ctx, matches[0])
+        ctx.fail(f"Ambiguous command '{cmd_name}'. Did you mean: {', '.join(sorted(matches))}?")
+        return None  # unreachable, but satisfies type checker
+
+
+@click.group(cls=AliasedGroup, invoke_without_command=True)
+@click.option("-v", "--verbose", is_flag=True, help="Enable verbose output.")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress informational output.")
+@click.version_option(version=__version__, prog_name="faden")
+@click.pass_context
+def cli(ctx: click.Context, *, verbose: bool, quiet: bool) -> None:
+    """faden — CLI installer and management tool for fadenstack."""
+    from faden_cli.core.detect import ensure_tool_path
+
+    # Make tools installed to ~/.local/bin / ~/.cargo/bin visible to
+    # every child subprocess, even when the current shell PATH lacks them
+    # (typical for fresh SSH sessions and GUI-launched terminals).
+    ensure_tool_path()
+
+    from faden_cli.core.docker_env import ensure_docker_host
+
+    # If the configured Docker endpoint is dead but Rancher Desktop's
+    # answers, export DOCKER_HOST so every docker subprocess (detect,
+    # compose, logs, …) reaches the live daemon.  No-op otherwise.
+    ensure_docker_host(verbose=verbose, quiet=quiet)
+
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+    ctx.obj["quiet"] = quiet
+
+    from faden_cli.core import update_check
+
+    # A newer release: checked while the command runs, said at its end.
+    update_check.start(ctx, quiet=quiet)
+
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ── Register subcommands ──────────────────────────────────────────
+
+def register_core_commands(group: click.Group | None = None) -> None:
+    """Import and register all core subcommand groups and commands.
+
+    Accepts an optional *group* parameter so the EE CLI can call this
+    with its own root group.  Defaults to ``cli`` when called internally.
+    """
+    target = group or cli
+
+    from faden_cli.commands.version import version_cmd
+    from faden_cli.commands.doctor import doctor_cmd
+    from faden_cli.commands.status import status_cmd
+    from faden_cli.commands.up import up_cmd
+    from faden_cli.commands.down import down_cmd
+    from faden_cli.commands.logs_cmd import logs_cmd
+    from faden_cli.commands.config import config_group
+    from faden_cli.commands.module import module_group
+    from faden_cli.commands.tune import tune_cmd
+    from faden_cli.commands.deploy import deploy_cmd
+    from faden_cli.commands.rebuild import rebuild_cmd
+    from faden_cli.commands.backup import backup_cmd
+    from faden_cli.commands.restore import restore_cmd
+    from faden_cli.commands.upgrade import upgrade_cmd
+    from faden_cli.commands.dev.dev_group import dev_group
+    from faden_cli.commands.admin import admin_group
+    from faden_cli.commands.observe import observe_group
+    from faden_cli.commands.runtime_images import runtime_images_cmd
+    from faden_cli.commands.tls import tls_group
+    from faden_cli.commands.ports import ports_cmd
+    from faden_cli.commands.maintenance import maintenance_group
+
+    target.add_command(version_cmd, "version")
+    target.add_command(doctor_cmd, "doctor")
+    target.add_command(status_cmd, "status")
+    target.add_command(up_cmd, "up")
+    target.add_command(down_cmd, "down")
+    target.add_command(logs_cmd, "logs")
+    target.add_command(config_group, "config")
+    target.add_command(module_group, "module")
+    target.add_command(tune_cmd, "tune")
+    target.add_command(deploy_cmd, "deploy")
+    target.add_command(rebuild_cmd, "rebuild")
+    target.add_command(backup_cmd, "backup")
+    target.add_command(restore_cmd, "restore")
+    target.add_command(upgrade_cmd, "upgrade")
+    target.add_command(dev_group, "dev")
+    target.add_command(admin_group, "admin")
+    target.add_command(observe_group, "observe")
+    target.add_command(runtime_images_cmd, "runtime-images")
+    target.add_command(tls_group, "tls")
+    target.add_command(ports_cmd, "ports")
+    target.add_command(maintenance_group, "maintenance")
+
+
+register_core_commands()
+
+
+def _use_utf8_output() -> None:
+    """Make the console accept the output this CLI actually produces.
+
+    Windows consoles default to cp1252, and this CLI writes arrows, box rules
+    and check marks -- some 17,000 non-ASCII characters across its sources.
+    Any one of them reaching a cp1252 stream raises UnicodeEncodeError, so
+    ``faden dev up --help`` ended in a traceback instead of printing help,
+    and redirecting any command to a file did the same.
+
+    ``errors="replace"`` rather than a hard switch: where a terminal genuinely
+    cannot represent a glyph, a degraded character is a far better outcome
+    than a stack trace standing in for the output.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:  # pytest capture, or a plain wrapper
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (OSError, ValueError):  # pragma: no cover - already detached
+            pass
+
+
+def main() -> None:
+    """Package entry point."""
+    _use_utf8_output()
+    cli()
+
+
+if __name__ == "__main__":
+    main()

faden_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations for the faden CLI."""

faden_cli/commands/admin.py

@@ -0,0 +1,161 @@
+"""``faden admin`` — administrative commands for a running deployment."""
+
+from __future__ import annotations
+
+import re
+import secrets
+import shutil
+import string
+import subprocess
+import sys
+
+import click
+
+from faden_cli.core.console import console, error, info, success, warning
+
+
+def _generate_password(length: int = 24) -> str:
+    """Generate a random password (letters + digits + punctuation subset)."""
+    alphabet = string.ascii_letters + string.digits + "!@#$%&*-_=+"
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+# Minimal email validation — rejects obvious injection attempts.
+_EMAIL_RE = re.compile(r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-.]+$")
+
+
+@click.group("admin")
+def admin_group() -> None:
+    """Administrative commands for a running Fadenstack deployment."""
+
+
+@admin_group.command("reset-password")
+@click.option(
+    "--email",
+    default="admin@localhost",
+    show_default=True,
+    help="Email address of the user whose password will be reset.",
+)
+@click.option(
+    "--password",
+    default=None,
+    help="New password.  Auto-generated if omitted.",
+)
+@click.option(
+    "-y", "--yes",
+    is_flag=True,
+    help="Skip confirmation prompt.",
+)
+def reset_password_cmd(*, email: str, password: str | None, yes: bool) -> None:
+    """Reset a user's password directly via the database.
+
+    This bypasses the API and sets the password hash in PostgreSQL.
+    The backend container must be running (needed for password hashing).
+    """
+    # Validate email early to prevent any injection
+    if not _EMAIL_RE.match(email):
+        error(f"Invalid email address: {email}")
+        sys.exit(1)
+
+    # The backend's rule for a new password (faden_backend/services/password_policy.py).
+    from faden_cli.core.bootstrap import MIN_PASSWORD_LENGTH  # noqa: PLC0415
+
+    if password is not None and len(password) < MIN_PASSWORD_LENGTH:
+        error(f"The password needs at least {MIN_PASSWORD_LENGTH} characters (or leave out --password).")
+        sys.exit(1)
+
+    docker = shutil.which("docker")
+    if not docker:
+        error("docker not found on PATH")
+        sys.exit(1)
+
+    new_password = password or _generate_password()
+
+    if not yes:
+        click.confirm(
+            f"Reset password for '{email}'?",
+            abort=True,
+        )
+
+    # ── 1. Hash the password inside the backend container ─────
+    info("Hashing new password…")
+    hash_script = (
+        "from fastapi_users.password import PasswordHelper; "
+        "print(PasswordHelper().hash(input()))"
+    )
+
+    hash_result = subprocess.run(  # noqa: S603
+        [
+            docker, "exec", "-i", "faden-backend",
+            "python", "-c", hash_script,
+        ],
+        input=new_password,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if hash_result.returncode != 0:
+        error("Failed to hash password — is the backend container running?")
+        if hash_result.stderr.strip():
+            error(f"  {hash_result.stderr.strip()}")
+        sys.exit(1)
+
+    hashed = hash_result.stdout.strip()
+    if not hashed:
+        error("Password hashing returned empty result.")
+        sys.exit(1)
+
+    # ── 2. Update the password in PostgreSQL ──────────────────
+    info("Updating password in database…")
+
+    # Both `hashed` (bcrypt output we generated) and `email` (validated
+    # above by regex) are safe for SQL string interpolation here.
+    sql = (
+        f"UPDATE \"user\" SET hashed_password = '{hashed}' "
+        f"WHERE email = '{email}';"
+    )
+
+    pg_result = subprocess.run(  # noqa: S603
+        [
+            docker, "exec", "faden-postgres",
+            "psql", "-U", "postgres", "-d", "faden_backend",
+            "-c", sql,
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if pg_result.returncode != 0:
+        error("Database update failed — is the postgres container running?")
+        if pg_result.stderr.strip():
+            error(f"  {pg_result.stderr.strip()}")
+        sys.exit(1)
+
+    # Check if a row was actually updated
+    if "UPDATE 0" in pg_result.stdout:
+        warning(f"No user found with email '{email}'.")
+        sys.exit(1)
+
+    success(f"Password reset for '{email}'.")
+
+    # ── 3. Display credentials ────────────────────────────────
+    from rich.panel import Panel
+    from rich.text import Text
+
+    lines = Text()
+    lines.append("  Email:     ", style="bold")
+    lines.append(email, style="cyan")
+    lines.append("\n  Password:  ", style="bold")
+    lines.append(new_password, style="cyan")
+    lines.append("\n\n  Store this in a password manager.", style="dim")
+
+    console.print()
+    console.print(
+        Panel(
+            lines,
+            title="[bold yellow]New Credentials[/bold yellow]",
+            border_style="yellow",
+            padding=(1, 2),
+        )
+    )

faden_cli/commands/backup.py

@@ -0,0 +1,159 @@
+"""``faden backup`` — create a backup of all databases and config.
+
+Examples:
+    faden backup                          # backup to ./backups
+    faden backup --output-dir /mnt/bak    # custom output directory
+    faden backup --include-volumes        # also snapshot Docker volumes
+    faden backup --db-only                # databases only, skip .env
+    faden backup --retain 3               # keep only 3 most recent
+    faden backup schedule                 # every night at 03:00, keep 7
+    faden backup schedule --off           # stop the nightly backup
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from faden_cli.core.backup import create_backup
+from faden_cli.core.compose import build_context_from_config
+from faden_cli.core.console import console, error, info, success, warning
+from faden_cli.core.private_files import private_dir
+from faden_cli.core.settings import load_config
+
+
+@click.group("backup", invoke_without_command=True)
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False),
+    default="backups",
+    show_default=True,
+    help="Directory to store backups in.",
+)
+@click.option(
+    "--include-volumes",
+    is_flag=True,
+    default=False,
+    help="Also snapshot the install's Docker volumes: knowledge-base uploads, MinIO, logs, traces, Grafana"
+    " (not Postgres's data, whose dumps are the backup, nor the models).",
+)
+@click.option(
+    "--retain",
+    type=int,
+    default=5,
+    show_default=True,
+    help="Keep only the N most recent backups.",
+)
+@click.option(
+    "--db-only",
+    is_flag=True,
+    default=False,
+    help="Dump databases only (skip .env and volumes).",
+)
+@click.option("-y", "--yes", is_flag=True, default=False, help="Skip confirmation prompt.")
+@click.pass_context
+def backup_cmd(
+    click_ctx: click.Context,
+    *,
+    output_dir: str,
+    include_volumes: bool,
+    retain: int,
+    db_only: bool,
+    yes: bool,
+) -> None:
+    """Create a backup of Fadenstack databases, config, and optionally volumes."""
+    if click_ctx.invoked_subcommand is not None:
+        return
+    console.print("\n[bold magenta]fadenstack — Backup[/bold magenta]\n")
+
+    cfg = load_config()
+    ctx = build_context_from_config(cfg)
+
+    output_path = Path(output_dir)
+    if not output_path.is_absolute():
+        output_path = cfg.install_path / output_path
+
+    if not yes:
+        click.confirm(
+            f"Create backup in {output_path}?",
+            default=True,
+            abort=True,
+        )
+
+    result = create_backup(
+        ctx,
+        output_dir=output_path,
+        include_volumes=include_volumes,
+        db_only=db_only,
+        retain=retain,
+    )
+
+    if not result.ok:
+        for msg in result.errors:
+            error(msg)
+        sys.exit(1)
+
+    console.print()
+    success(f"Backup created: {result.backup_dir}")
+    console.print(f"  Databases: {', '.join(result.databases)}")
+    if result.env_snapshot:
+        console.print(f"  .env snapshot: {result.env_snapshot}")
+    if result.volumes:
+        console.print(f"  Volumes: {', '.join(result.volumes)}")
+    if result.tls_material:
+        console.print(
+            f"  Certificate material: {len(result.tls_material)} file(s), private keys among them;"
+            " keep the backup as private as .env"
+        )
+    if result.manifest_path:
+        console.print(f"  Manifest: {result.manifest_path.name}")
+
+
+@backup_cmd.command("schedule")
+@click.option("--at", "at", default="03:00", show_default=True, help="Time of day, HH:MM (server time).")
+@click.option("--retain", type=int, default=7, show_default=True, help="Keep the N most recent backups.")
+@click.option("--off", is_flag=True, default=False, help="Stop the nightly backup.")
+def schedule_cmd(*, at: str, retain: int, off: bool) -> None:
+    """Back up every night, keeping the most recent few.
+
+    The backups land in <install_dir>/backups/, on the same disk as the
+    data: copy them elsewhere too (or pass --output-dir to a mounted disk
+    with `faden backup` from your own scheduler).
+    """
+    from faden_cli.core import schedule  # noqa: PLC0415
+
+    if not schedule.available():
+        error("No systemd user manager or cron here: schedule `faden backup -y` with your own scheduler.")
+        sys.exit(1)
+    if off:
+        if schedule.remove():
+            success("Nightly backup stopped.")
+        else:
+            info("No nightly backup was scheduled.")
+        return
+    try:
+        hour, minute = (int(part) for part in at.split(":", 1))
+        if not (0 <= hour < 24 and 0 <= minute < 60):  # noqa: PLR2004
+            raise ValueError
+    except ValueError:
+        error(f"--at wants HH:MM, got {at!r}.")
+        sys.exit(2)
+    if retain < 1:
+        error("--retain must keep at least one backup.")
+        sys.exit(2)
+    cfg = load_config()
+    if not cfg.install_dir:
+        error("No install to back up: run `faden deploy` first.")
+        sys.exit(1)
+    backups = private_dir(cfg.install_path / "backups")
+    try:
+        how, warnings = schedule.install(hour=hour, minute=minute, retain=retain, log=backups / "backup.log")
+    except (RuntimeError, OSError) as exc:
+        error(f"Could not schedule the backup: {exc}")
+        sys.exit(1)
+    success(f"Backing up every night at {hour:02d}:{minute:02d}, keeping {retain}: {backups} ({how})")
+    for message in warnings:
+        warning(message)
+    warning("The backups are on the same disk as the data; copy them elsewhere too.")

faden_cli/commands/config.py

@@ -0,0 +1,146 @@
+"""``faden config`` — view and manage configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import yaml
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from faden_cli.core.console import console, success, error
+from faden_cli.core.settings import load_config, save_config, config_path
+
+
+@click.group("config")
+def config_group() -> None:
+    """Manage faden configuration."""
+
+
+@config_group.command("show")
+def config_show() -> None:
+    """Display the current configuration."""
+    cfg_path = config_path()
+
+    if not cfg_path.exists():
+        console.print(f"[dim]No config file found at {cfg_path}[/dim]")
+        console.print("[dim]Using default configuration.[/dim]")
+        cfg = load_config()
+        import dataclasses
+
+        raw = yaml.dump(dataclasses.asdict(cfg), default_flow_style=False, sort_keys=False)
+        console.print(Panel(Syntax(raw, "yaml", theme="monokai"), title="defaults"))
+        return
+
+    raw = cfg_path.read_text(encoding="utf-8")
+    console.print(
+        Panel(
+            Syntax(raw, "yaml", theme="monokai"),
+            title=str(cfg_path),
+            border_style="cyan",
+        )
+    )
+
+
+@config_group.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str) -> None:
+    """Set a configuration value (dot-notation supported).
+
+    Examples:
+
+        faden config set install_dir /opt/faden
+
+        faden config set dev.branch main
+    """
+    cfg = load_config()
+    import dataclasses
+
+    cfg_dict = dataclasses.asdict(cfg)
+
+    # Support dot-notation for nested keys (e.g., dev.branch)
+    parts = key.split(".")
+    target = cfg_dict
+    for part in parts[:-1]:
+        if part not in target or not isinstance(target[part], dict):
+            error(f"Unknown config section: {part}")
+            return
+        target = target[part]
+
+    final_key = parts[-1]
+    if final_key not in target:
+        error(f"Unknown config key: {key}")
+        return
+
+    # Coerce value types
+    old_val = target[final_key]
+    if isinstance(old_val, bool):
+        value_typed: str | bool | int | float | list[str] = value.lower() in ("true", "1", "yes")
+    elif isinstance(old_val, int):
+        value_typed = int(value)
+    elif isinstance(old_val, float):
+        value_typed = float(value)
+    elif isinstance(old_val, list):
+        value_typed = [v.strip() for v in value.split(",")]
+    else:
+        value_typed = value
+
+    target[final_key] = value_typed
+
+    # Rebuild config
+    from faden_cli.core.settings import FadenConfig, DevConfig
+
+    dev_data = cfg_dict.pop("dev", {}) or {}
+    dev_cfg = DevConfig(**{k: v for k, v in dev_data.items() if k in DevConfig.__dataclass_fields__})
+    new_cfg = FadenConfig(**cfg_dict, dev=dev_cfg)
+
+    save_config(new_cfg)
+    success(f"Set {key} = {value_typed}")
+
+
+@config_group.command("path")
+def config_path_cmd() -> None:
+    """Print the config file path."""
+    click.echo(str(config_path()))
+
+
+@config_group.command("init")
+@click.option("--force", is_flag=True, help="Overwrite existing config file.")
+def config_init(*, force: bool) -> None:
+    """Create a default configuration file."""
+    cfg_file = config_path()
+
+    if cfg_file.exists() and not force:
+        error(f"Config file already exists at {cfg_file}. Use --force to overwrite.")
+        return
+
+    cfg = load_config()
+    save_config(cfg)
+    success(f"Configuration written to {cfg_file}")
+
+
+@config_group.command("edit")
+def config_edit() -> None:
+    """Open the config file in $EDITOR."""
+    import os
+    import subprocess
+
+    cfg_file = config_path()
+    if not cfg_file.exists():
+        # Create default first
+        cfg = load_config()
+        save_config(cfg)
+
+    editor = os.environ.get("EDITOR", os.environ.get("VISUAL", ""))
+    if not editor:
+        # Fallback based on platform
+        import platform
+
+        if platform.system() == "Windows":
+            editor = "notepad"
+        else:
+            editor = "nano"
+
+    subprocess.run([editor, str(cfg_file)], check=False)