fadenstack 0.4.2__py3-none-any.whl

faden_cli/core/git.py

@@ -0,0 +1,219 @@
+"""Git clone and checkout helpers for dev mode.
+
+Provides functions to clone repositories from the ``fadenstack`` GitHub
+organisation, with support for HTTPS (default) and SSH clone methods.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from faden_cli.core.console import console, error, info, success, warning
+from faden_cli.core.registry import CORE_REPO, REPO_DIR_MAP, core_repo_clone_url, repo_clone_url
+
+
+@dataclass
+class CloneResult:
+    """Result of a single repo clone operation."""
+
+    repo: str
+    local_dir: str
+    cloned: bool = False
+    skipped: bool = False
+    error: str = ""
+
+
+def clone_repo(
+    repo: str,
+    *,
+    target_dir: Path,
+    method: str = "https",
+    branch: str | None = None,
+    force: bool = False,
+    token: str = "",
+) -> CloneResult:
+    """Clone a single repo into ``target_dir / local_name``.
+
+    Skips if the directory already exists unless *force* is True,
+    in which case it runs ``git pull`` to update instead.
+    """
+    local_name = REPO_DIR_MAP.get(repo, repo)
+    dest = target_dir / local_name
+    result = CloneResult(repo=repo, local_dir=str(dest))
+
+    if dest.exists():
+        if force:
+            git = shutil.which("git")
+            if not git:
+                result.error = "git not found on PATH"
+                return result
+            try:
+                proc = subprocess.run(
+                    [git, "pull"],
+                    cwd=str(dest),
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                )
+                if proc.returncode == 0:
+                    result.cloned = True  # updated
+                else:
+                    result.error = proc.stderr.strip() or f"git pull exited with code {proc.returncode}"
+            except subprocess.TimeoutExpired:
+                result.error = "git pull timed out after 120s"
+            except OSError as exc:
+                result.error = str(exc)
+            return result
+        else:
+            result.skipped = True
+            return result
+
+    git = shutil.which("git")
+    if not git:
+        result.error = "git not found on PATH"
+        return result
+
+    url = repo_clone_url(repo, method=method, token=token)
+    cmd: list[str] = [git, "clone", url, str(dest)]
+    if branch:
+        cmd.extend(["--branch", branch])
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=120)  # noqa: S603
+        if proc.returncode == 0:
+            result.cloned = True
+        else:
+            result.error = proc.stderr.strip() or f"git clone exited with code {proc.returncode}"
+    except subprocess.TimeoutExpired:
+        result.error = "git clone timed out after 120s"
+    except OSError as exc:
+        result.error = str(exc)
+
+    return result
+
+
+def clone_all_repos(
+    repos: list[str],
+    *,
+    target_dir: Path,
+    method: str = "https",
+    branch: str | None = None,
+    force: bool = False,
+    token: str = "",
+) -> list[CloneResult]:
+    """Clone all repos into the target directory.
+
+    Clones the core monorepo once and all subdirectories are available
+    immediately. Falls back to individual repo clones for repos not
+    in the monorepo (e.g. EE add-ons).
+    """
+    target_dir.mkdir(parents=True, exist_ok=True)
+    results: list[CloneResult] = []
+
+    # Clone the core monorepo first
+    with console.status("[bold cyan]Cloning core monorepo…") as _status:
+        core_dest = target_dir / CORE_REPO
+        core_result = CloneResult(repo=CORE_REPO, local_dir=str(core_dest))
+
+        if core_dest.exists():
+            if force:
+                git = shutil.which("git")
+                if git:
+                    try:
+                        proc = subprocess.run(
+                            [git, "pull"], cwd=str(core_dest),
+                            capture_output=True, text=True, timeout=120,
+                        )
+                        core_result.cloned = proc.returncode == 0
+                        if not core_result.cloned:
+                            core_result.error = proc.stderr.strip()
+                    except (subprocess.TimeoutExpired, OSError) as exc:
+                        core_result.error = str(exc)
+                else:
+                    core_result.error = "git not found on PATH"
+            else:
+                core_result.skipped = True
+        else:
+            git = shutil.which("git")
+            if not git:
+                core_result.error = "git not found on PATH"
+            else:
+                url = core_repo_clone_url(method=method, token=token)
+                cmd: list[str] = [git, "clone", url, str(core_dest)]
+                if branch:
+                    cmd.extend(["--branch", branch])
+                try:
+                    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=300)  # noqa: S603
+                    core_result.cloned = proc.returncode == 0
+                    if not core_result.cloned:
+                        core_result.error = proc.stderr.strip()
+                except (subprocess.TimeoutExpired, OSError) as exc:
+                    core_result.error = str(exc)
+
+        results.append(core_result)
+        if core_result.skipped:
+            warning(f"{CORE_REPO} → already exists, skipped")
+        elif core_result.cloned:
+            success(f"{CORE_REPO} → cloned")
+        else:
+            error(f"{CORE_REPO} → {core_result.error}")
+
+    # Clone any remaining repos not in the monorepo (e.g. EE repos)
+    monorepo_dirs = {r.local_dir for r in __import__("faden_cli.core.registry", fromlist=["REPOS"]).REPOS}
+    extra_repos = [r for r in repos if REPO_DIR_MAP.get(r, r) not in monorepo_dirs]
+
+    if extra_repos:
+        with console.status("[bold cyan]Cloning additional repositories…") as _status:
+            for repo in extra_repos:
+                _status.update(f"Cloning [bold]{repo}[/bold]…")
+                res = clone_repo(repo, target_dir=target_dir, method=method, branch=branch, force=force, token=token)
+                results.append(res)
+
+                if res.skipped:
+                    warning(f"{repo} → already exists, skipped")
+                elif res.cloned:
+                    success(f"{repo} → cloned")
+                else:
+                    error(f"{repo} → {res.error}")
+
+    return results
+
+
+def checkout_branch(repo_dir: Path, branch: str) -> bool:
+    """Checkout a branch in an existing repo."""
+    git = shutil.which("git")
+    if not git:
+        return False
+    try:
+        result = subprocess.run(  # noqa: S603
+            [git, "checkout", branch],
+            cwd=str(repo_dir),
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def current_branch(repo_dir: Path) -> str:
+    """Get the current branch of a repo."""
+    git = shutil.which("git")
+    if not git:
+        return "unknown"
+    try:
+        result = subprocess.run(  # noqa: S603
+            [git, "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=str(repo_dir),
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return result.stdout.strip() if result.returncode == 0 else "unknown"
+    except (subprocess.TimeoutExpired, OSError):
+        return "unknown"

faden_cli/core/install.py

@@ -0,0 +1,288 @@
+"""Cross-platform prerequisite installer.
+
+Supports Windows (winget / scoop), macOS (brew), and
+Linux (apt / dnf / pacman / zypper).  Each tool declares
+install commands per platform+manager pair.  Docker is
+intentionally excluded — it requires admin, reboots, and
+kernel-level setup that can't be safely automated.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+from faden_cli.core.console import console, error, info, success, warning
+
+
+# ── Types ─────────────────────────────────────────────────────────
+
+@dataclass
+class Prerequisite:
+    """A required CLI tool with platform-specific install commands."""
+
+    name: str
+    check_cmd: str  # binary name on PATH
+    required: bool = True  # False = optional (warn only)
+    install_commands: dict[str, list[str]] = field(default_factory=dict)
+    post_install_hint: str = ""
+
+
+# ── Platform / package-manager detection ──────────────────────────
+
+def _detect_platform_key() -> str:
+    """Return a key like ``windows/winget``, ``darwin/brew``, ``linux/apt``."""
+    system = platform.system().lower()
+
+    if system == "windows":
+        for mgr in ("winget", "scoop", "choco"):
+            if shutil.which(mgr):
+                return f"windows/{mgr}"
+        return "windows/winget"  # fallback label
+
+    if system == "darwin":
+        if shutil.which("brew"):
+            return "darwin/brew"
+        return "darwin/brew"
+
+    # Linux — detect package manager
+    for mgr in ("apt", "dnf", "pacman", "zypper"):
+        if shutil.which(mgr):
+            return f"linux/{mgr}"
+    return "linux/unknown"
+
+
+# ── Tool definitions ─────────────────────────────────────────────
+
+_UV = Prerequisite(
+    name="uv",
+    check_cmd="uv",
+    install_commands={
+        "windows/winget": ["powershell", "-NoProfile", "-Command",
+                           "irm https://astral.sh/uv/install.ps1 | iex"],
+        "windows/scoop": ["scoop", "install", "uv"],
+        "windows/choco": ["choco", "install", "uv", "-y"],
+        "darwin/brew": ["brew", "install", "uv"],
+        "linux/apt": ["sh", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"],
+        "linux/dnf": ["sh", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"],
+        "linux/pacman": ["sh", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"],
+        "linux/zypper": ["sh", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"],
+    },
+    post_install_hint="You may need to restart your shell for uv to be on PATH.",
+)
+
+_GIT = Prerequisite(
+    name="git",
+    check_cmd="git",
+    install_commands={
+        "windows/winget": ["winget", "install", "--id", "Git.Git",
+                           "--source", "winget", "--accept-package-agreements",
+                           "--accept-source-agreements"],
+        "windows/scoop": ["scoop", "install", "git"],
+        "windows/choco": ["choco", "install", "git", "-y"],
+        "darwin/brew": ["brew", "install", "git"],
+        "linux/apt": ["sudo", "apt", "install", "-y", "git"],
+        "linux/dnf": ["sudo", "dnf", "install", "-y", "git"],
+        "linux/pacman": ["sudo", "pacman", "-S", "--noconfirm", "git"],
+        "linux/zypper": ["sudo", "zypper", "install", "-y", "git"],
+    },
+)
+
+_NODE = Prerequisite(
+    name="node",
+    check_cmd="node",
+    install_commands={
+        "windows/winget": ["winget", "install", "--id", "OpenJS.NodeJS.LTS",
+                           "--source", "winget", "--accept-package-agreements",
+                           "--accept-source-agreements"],
+        "windows/scoop": ["scoop", "install", "nodejs-lts"],
+        "windows/choco": ["choco", "install", "nodejs-lts", "-y"],
+        "darwin/brew": ["brew", "install", "node"],
+        "linux/apt": ["sudo", "apt", "install", "-y", "nodejs", "npm"],
+        "linux/dnf": ["sudo", "dnf", "install", "-y", "nodejs", "npm"],
+        "linux/pacman": ["sudo", "pacman", "-S", "--noconfirm", "nodejs", "npm"],
+        "linux/zypper": ["sudo", "zypper", "install", "-y", "nodejs", "npm"],
+    },
+    post_install_hint="You may need to restart your shell for node/npm to be on PATH.",
+)
+
+_DOCKER = Prerequisite(
+    name="docker",
+    check_cmd="docker",
+    install_commands={},  # intentionally empty — manual only
+    post_install_hint=(
+        "Docker requires manual installation:\n"
+        "  Windows / macOS: https://docs.docker.com/desktop/\n"
+        "  Linux:           https://docs.docker.com/engine/install/"
+    ),
+)
+
+DEV_PREREQUISITES: list[Prerequisite] = [_DOCKER, _GIT, _UV, _NODE]
+
+
+# ── Check logic ──────────────────────────────────────────────────
+
+@dataclass
+class CheckResult:
+    """Result of checking a single prerequisite."""
+
+    prereq: Prerequisite
+    found: bool
+    version: str = ""
+    installable: bool = False  # True if we have an install command for this platform
+
+
+def check_prerequisites(
+    prereqs: list[Prerequisite] | None = None,
+) -> list[CheckResult]:
+    """Check which prerequisites are present on the system."""
+    from faden_cli.core.detect import check_tool  # noqa: PLC0415
+
+    prereqs = prereqs or DEV_PREREQUISITES
+    platform_key = _detect_platform_key()
+    results: list[CheckResult] = []
+
+    for p in prereqs:
+        tc = check_tool(p.check_cmd)
+        installable = bool(p.install_commands.get(platform_key))
+        results.append(
+            CheckResult(
+                prereq=p,
+                found=tc.found,
+                version=tc.version,
+                installable=installable,
+            ),
+        )
+    return results
+
+
+# ── Install logic ────────────────────────────────────────────────
+
+def _add_to_session_path(directory: str) -> None:
+    """Prepend a tool directory to this process's PATH.
+
+    Lets a freshly installed binary (e.g. uv in ~/.local/bin) be invoked
+    by later subprocess calls in the same CLI run without a shell restart.
+    """
+    current = os.environ.get("PATH", "")
+    parts = current.split(os.pathsep)
+    if directory in parts:
+        return
+    os.environ["PATH"] = directory + (os.pathsep + current if current else "")
+
+
+def _run_install(cmd: list[str], name: str) -> bool:
+    """Run an install command and return True on success."""
+    console.print(f"  [cyan]Installing {name}…[/cyan]")
+    try:
+        result = subprocess.run(  # noqa: S603
+            cmd,
+            timeout=300,
+            check=False,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+        error(f"  Install command failed: {exc}")
+        return False
+
+
+def install_missing(
+    results: list[CheckResult],
+    *,
+    auto_confirm: bool = False,
+) -> list[CheckResult]:
+    """Attempt to install missing prerequisites.
+
+    Returns the subset that were successfully installed.
+    """
+    platform_key = _detect_platform_key()
+    missing = [r for r in results if not r.found]
+
+    if not missing:
+        return []
+
+    installable = [r for r in missing if r.installable]
+    manual_only = [r for r in missing if not r.installable]
+
+    if manual_only:
+        for r in manual_only:
+            warning(f"  {r.prereq.name}: cannot be auto-installed on this platform.")
+            if r.prereq.post_install_hint:
+                console.print(f"    [dim]{r.prereq.post_install_hint}[/dim]")
+
+    if not installable:
+        return []
+
+    names = ", ".join(r.prereq.name for r in installable)
+    if not auto_confirm:
+        import click  # noqa: PLC0415
+
+        if not click.confirm(f"Install missing tools ({names})?", default=True):
+            info("Skipping prerequisite installation.")
+            return []
+
+    installed: list[CheckResult] = []
+    for r in installable:
+        cmd = r.prereq.install_commands[platform_key]
+        if _run_install(cmd, r.prereq.name):
+            # Re-check after install — the binary might not be on
+            # the current PATH yet (e.g. uv installer adds to
+            # ~/.local/bin which isn't in this session's PATH).
+            from faden_cli.core.detect import check_tool  # noqa: PLC0415
+
+            tc = check_tool(r.prereq.check_cmd)
+            if tc.found:
+                # Make the tool usable by this run's subprocess calls too.
+                _add_to_session_path(os.path.dirname(tc.path))
+                success(f"  {r.prereq.name} {tc.version} ✓")
+                installed.append(r)
+            else:
+                warning(f"  {r.prereq.name} installed but not yet on PATH.")
+                if r.prereq.post_install_hint:
+                    console.print(f"    [dim]{r.prereq.post_install_hint}[/dim]")
+                installed.append(r)  # still count as installed
+        else:
+            error(f"  Failed to install {r.prereq.name}.")
+    return installed
+
+
+# ── Convenience — run full check + optional install ──────────────
+
+def ensure_prerequisites(
+    *,
+    install: bool = False,
+    auto_confirm: bool = False,
+) -> bool:
+    """Check prerequisites and optionally install missing ones.
+
+    Returns True if all required tools are available (or were installed).
+    """
+    results = check_prerequisites()
+
+    has_missing = False
+    for r in results:
+        mark = "[green]✓[/green]" if r.found else "[red]✗[/red]"
+        ver = f" {r.version}" if r.version else ""
+        console.print(f"  {mark} {r.prereq.name}{ver}")
+        if not r.found and r.prereq.required:
+            has_missing = True
+
+    if not has_missing:
+        return True
+
+    if install:
+        installed = install_missing(results, auto_confirm=auto_confirm)
+        # Re-check required tools
+        remaining = check_prerequisites()
+        still_missing = [r for r in remaining if not r.found and r.prereq.required]
+        if not still_missing:
+            return True
+        for r in still_missing:
+            error(f"  {r.prereq.name} is still missing.")
+        return False
+
+    return False

faden_cli/core/installation.py

@@ -0,0 +1,186 @@
+"""What a Fadenstack installation runs: its release, or the code its images were built from.
+
+An install made from the published images carries the release it was unpacked from (``.faden-release``,
+:mod:`faden_cli.core.bundle`); its images are that release's. A source checkout builds its images from
+whatever the checkout holds at the time, and the checkout can move on afterwards -- so ``faden upgrade`` and
+``faden deploy`` record, when they build, which commit the images came from (:data:`BUILD_RECORD`).
+``faden version`` reads both, so an operator can always say what the server runs.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+
+from faden_cli import __version__
+from faden_cli.core.bundle import installed_release
+
+#: Written into the install directory when its images are built from a checkout.
+BUILD_RECORD = ".faden-build"
+
+#: Tracked files the running install rewrites itself: a change to them is not a local change to the code.
+GENERATED = frozenset({
+    "shared/prometheus/targets.json", "shared/rabbitmq/definitions.json", "shared/rabbitmq/10-faden.conf",
+})
+
+_AGENT_VERSION = re.compile(r'^AGENT_VERSION\s*=\s*"([^"]+)"', re.MULTILINE)
+
+
+def checkout_of(install_dir: Path) -> Path | None:
+    """The source checkout an install directory belongs to (``<checkout>/shared``), or ``None``."""
+    for candidate in (install_dir, *install_dir.parents[:2]):
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def _git(repo: Path, *args: str) -> str | None:
+    try:
+        out = subprocess.run(  # noqa: S603
+            ["git", "-C", str(repo), *args],  # noqa: S607
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip() if out.returncode == 0 and out.stdout.strip() else None
+
+
+def checkout_state(repo: Path) -> dict[str, str | bool | None]:
+    """The checkout's commit, a readable name for it, and whether it has local changes.
+
+    The name is the release the commit follows (``v0.4.1-3-gabc1234``), or the commit when no release tag is
+    reachable; the repository's other tags (the agent's, older ones) say nothing about the server.
+    """
+    changed = (_git(repo, "diff", "--name-only", "HEAD") or "").splitlines()
+    commit = _git(repo, "rev-parse", "--short=8", "HEAD")
+    return {
+        "commit": commit,
+        "describe": _git(repo, "describe", "--tags", "--match", "v[0-9]*") or commit,
+        "branch": _git(repo, "symbolic-ref", "--short", "-q", "HEAD"),
+        "modified": any(path not in GENERATED for path in changed),
+    }
+
+
+def record_build(install_dir: Path, *, complete: bool = True) -> dict | None:
+    """Note which commit this install's images were just built from; ``None`` outside a checkout.
+
+    ``complete`` is false when some images failed to build: those still run the code of an earlier build.
+    """
+    repo = checkout_of(install_dir)
+    if repo is None:
+        return None
+    record = {
+        **checkout_state(repo),
+        "built_at": datetime.now(tz=UTC).isoformat(timespec="seconds"),
+        "complete": complete,
+        "cli": __version__,
+    }
+    try:
+        (install_dir / BUILD_RECORD).write_text(json.dumps(record) + "\n", encoding="utf-8")
+    except OSError:
+        return None
+    return record
+
+
+def read_build(install_dir: Path) -> dict | None:
+    """What :func:`record_build` noted last, or ``None``."""
+    try:
+        return json.loads((install_dir / BUILD_RECORD).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _env_value(env_file: Path, key: str) -> str | None:
+    try:
+        for line in env_file.read_text(encoding="utf-8").splitlines():
+            if line.startswith(f"{key}="):
+                return line.split("=", 1)[1].strip().strip('"').strip("'") or None
+    except OSError:
+        return None
+    return None
+
+
+def _agent_version(repo: Path | None) -> str | None:
+    if repo is None:
+        return None
+    try:
+        text = (repo / "backend/faden_backend/web/api/install/__init__.py").read_text(encoding="utf-8")
+    except OSError:
+        return None
+    m = _AGENT_VERSION.search(text)
+    return m.group(1) if m else None
+
+
+def _runtimes(repo: Path | None) -> list[str]:
+    """The runtimes the server offers its machines, from the runtime manifests it ships."""
+    if repo is None:
+        return []
+    out = []
+    for path in sorted((repo / "runtime-image").glob("runtime-manifest*.json")):
+        try:
+            m = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        cert = m.get("certification") if isinstance(m.get("certification"), dict) else {}
+        status = cert.get("overall_status") or m.get("overall_status") or "uncertified"
+        channel = cert.get("channel")
+        out.append(f"{m.get('runtime_id', path.stem)} ({status}{', ' + channel if channel else ''})")
+    return out
+
+
+def describe(install_dir: Path) -> list[tuple[str, str]]:
+    """Rows for ``faden version``: what this installation runs."""
+    rows: list[tuple[str, str]] = [("Install directory", str(install_dir))]
+    if not install_dir.is_dir():
+        rows.append(
+            ("Installed", "[red]not found -- run 'faden deploy', or set install_dir in faden.yaml[/red]")
+        )
+        return rows
+    release = installed_release(install_dir)
+    repo = checkout_of(install_dir)
+    if release is not None:
+        rows.append(("Installed", f"release {release} (published images)"))
+    elif repo is not None:
+        state = checkout_state(repo)
+        now = state.get("describe") or state.get("commit") or "unknown"
+        where = f" on {state['branch']}" if state.get("branch") else " (detached)"
+        changed = ", with local changes" if state.get("modified") else ""
+        rows.append(("Installed", f"source checkout at {now}{where}{changed}"))
+        build = read_build(install_dir)
+        if build:
+            built = build.get("describe") or build.get("commit") or "unknown"
+            notes = []
+            if build.get("modified"):
+                notes.append("with local changes")
+            if build.get("complete") is False:
+                notes.append("[yellow]some images failed to build[/yellow]")
+            if build.get("commit") != state.get("commit"):
+                notes.append("[yellow]checkout has moved since[/yellow]")
+            note = f" ({'; '.join(notes)})" if notes else ""
+            rows.append(("Images built from", f"{built}, {build.get('built_at', '?')}{note}"))
+        else:
+            rows.append(
+                (
+                    "Images built from",
+                    "not recorded (built before this was kept; the next upgrade records it)",
+                )
+            )
+    else:
+        rows.append(
+            ("Installed", "[yellow]unknown (no release marker, not a source checkout)[/yellow]"),
+        )
+
+    tag = _env_value(install_dir / ".env", "VERSION")
+    rows.append(("Image tag", tag or "latest"))
+    agent = _agent_version(repo)
+    if agent:
+        rows.append(("Machine agent", f"{agent} (handed out by the install line)"))
+    for i, runtime in enumerate(_runtimes(repo)):
+        rows.append(("Runtimes" if i == 0 else "", runtime))
+    return rows