terraui 0.1.0__py3-none-any.whl

terraui/__init__.py

@@ -0,0 +1,3 @@
+"""TerraUi — local-first control plane for Terraform & Terragrunt."""
+
+__version__ = "0.1.0"

terraui/ai/chat.py

@@ -0,0 +1,98 @@
+"""AI assistant proxy (BACKEND_SPEC §12).
+
+Grounds answers in the user's stacks (drift, locks, run-all, auth) and proxies to
+Claude when ANTHROPIC_API_KEY is set. The model key never touches the browser.
+Falls back to canned, useful answers when no key / SDK is available so the chat
+always works offline.
+"""
+
+from __future__ import annotations
+
+import os
+
+MODEL = "claude-haiku-4-5"  # mirrors the "Haiku" badge in the frontend
+
+PERSONA = (
+    "You are TerraUi Assistant, an expert platform/SRE engineer specializing in "
+    "Terraform and Terragrunt across AWS, GCP and Azure. The user manages many IaC "
+    "stacks in one UI (drift, state locking, run-all orchestration, PR-triggered "
+    "plans). Answer concisely and practically, with short code/command snippets "
+    "where useful. Keep under 170 words. You may read state and run read-only "
+    "commands, but never apply changes without explicit human approval."
+)
+
+
+def _fallback(q: str) -> str:
+    low = q.lower()
+    if "drift" in low:
+        return (
+            "Drift means the live resource no longer matches your recorded state — something "
+            "changed outside Terraform.\n\nInspect it: open the stack → Drift tab for attribute-level "
+            "state-vs-actual. To reconcile, run a plan — Terraform shows the changes needed to bring "
+            "reality back in line, then apply.\n\nPrevent it: restrict console/CLI write access in prod "
+            "and rely on PR-driven applies."
+        )
+    if "lock" in low:
+        return (
+            "State locking stops two applies from corrupting state.\n\n"
+            "• AWS (S3 backend): add a DynamoDB table → dynamodb_table = \"acme-tf-locks\".\n"
+            "• GCS / azurerm: locking is built in.\n\nIn TerraUi the Lock column shows who holds it. "
+            "If a run dies and leaves a stale lock, release it from the stack's Overview "
+            "(or terraform force-unlock LOCK_ID)."
+        )
+    if "run-all" in low or "order" in low or "depend" in low:
+        return (
+            "terragrunt run-all apply walks every unit and applies them in dependency order (from "
+            "dependency{} blocks) — e.g. networking before eks-cluster.\n\nPlain terraform apply only "
+            "touches the current module. Use the Dependencies view to preview the run-all order before "
+            "you trigger it."
+        )
+    if "adc" in low or "gcloud" in low or "gcp" in low:
+        return (
+            "GCP needs two logins:\n\n  gcloud auth login                       # your user identity for gcloud\n"
+            "  gcloud auth application-default login    # ADC, what Terraform uses\n\nThe Terraform google "
+            "provider reads ADC, not your gcloud user session — that's why both are required. Set the "
+            "project with gcloud config set project."
+        )
+    if "import" in low:
+        return (
+            "Use terraform import to bring an existing resource under management:\n\n"
+            "  terraform import aws_s3_bucket.logs acme-logs-bucket\n\nDefine the resource block first, "
+            "import, then run plan to confirm zero diff. For bulk imports, Terraform 1.5+ supports "
+            "import{} blocks in config."
+        )
+    return (
+        "I can help with Terraform/Terragrunt: drift, state & locking, run-all ordering, provider auth "
+        "(AWS/GCP/Azure), plan/apply flags, imports and module structure. Ask me something specific — "
+        'e.g. "why is eks-cluster drifting?" or "set up remote state locking".'
+    )
+
+
+async def chat(question: str, context: str = "") -> dict:
+    """Return {reply, model, grounded} for a single assistant turn."""
+    question = (question or "").strip()
+    if not question:
+        return {"reply": "", "model": "none", "grounded": False}
+
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return {"reply": _fallback(question), "model": "fallback", "grounded": False}
+
+    try:
+        import anthropic  # optional dependency
+    except ImportError:
+        return {"reply": _fallback(question), "model": "fallback", "grounded": False}
+
+    system = PERSONA + (f"\n\nCurrent stack context:\n{context}" if context else "")
+    try:
+        client = anthropic.AsyncAnthropic(api_key=api_key)
+        resp = await client.messages.create(
+            model=MODEL,
+            max_tokens=1024,
+            system=system,
+            messages=[{"role": "user", "content": question}],
+        )
+        text = "".join(b.text for b in resp.content if getattr(b, "type", "") == "text")
+        return {"reply": text.strip() or _fallback(question), "model": MODEL, "grounded": bool(context)}
+    except Exception:
+        return {"reply": _fallback(question), "model": "fallback", "grounded": False}

terraui/cli.py

@@ -0,0 +1,242 @@
+"""TerraUi CLI (BACKEND_SPEC §2): start | scan | setup | server | agent."""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import __version__
+
+app = typer.Typer(add_completion=False, help="Local-first control plane for Terraform & Terragrunt.")
+
+
+def _version_cb(value: bool):
+    if value:
+        typer.echo(f"terraui {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", callback=_version_cb, is_eager=True, help="Show version and exit."),
+):
+    """TerraUi — inventory, plan/apply, drift, locks and a cloud shell, in one UI."""
+
+
+# ---- preflight helpers (cloud SDK detect / install / auth) ----------------
+def _clouds_from_stacks(stacks: list[dict]) -> list[str]:
+    seen: list[str] = []
+    for s in stacks:
+        for c in (s.get("clouds") or [s.get("prov")]):
+            if c and c not in seen:
+                seen.append(c)
+    return seen
+
+
+def _status_line(st) -> str:
+    if not st.installed:
+        return typer.style(f"  ✗ {st.name:6} CLI not installed", fg="yellow")
+    if not st.authed:
+        return typer.style(f"  ⚠ {st.name:6} {st.version} · not authenticated ({st.detail})", fg="yellow")
+    return typer.style(f"  ✓ {st.name:6} {st.version} · {st.detail}", fg="green")
+
+
+def _quick_check(provider_ids: list[str]) -> None:
+    """Read-only summary printed before serving. Never blocks."""
+    from .clouds import preflight
+
+    if not provider_ids:
+        return
+    typer.echo("Cloud SDK status (providers used by your stacks):")
+    needs_setup = False
+    for st in preflight.check_all(provider_ids):
+        typer.echo(_status_line(st))
+        if not st.installed or not st.authed:
+            needs_setup = True
+    if needs_setup:
+        typer.echo(typer.style("  → run `terraui setup` to install / authenticate (you can skip providers).", fg="cyan"))
+
+
+def _interactive_setup(provider_ids: list[str], assume_yes: bool = False) -> None:
+    """Per-provider install + auth, fully skippable. Shows the exact command first."""
+    from .clouds import preflight
+
+    interactive = sys.stdin.isatty() and not assume_yes
+    typer.echo(typer.style(f"\nTerraUi setup — configuring: {', '.join(provider_ids)}\n", bold=True))
+
+    for pid in provider_ids:
+        st = preflight.check(pid)
+        typer.echo(typer.style(f"{st.name}", bold=True))
+
+        # 1) install if missing
+        if not st.installed:
+            argv, url = preflight.install_command(pid)
+            if argv:
+                cmd = " ".join(argv)
+                typer.echo(f"  CLI not found. Install command: {typer.style(cmd, fg='cyan')}")
+                do = assume_yes or (interactive and typer.confirm("  Run it now?", default=True))
+                if do:
+                    ok = preflight.run_install(pid)
+                    typer.echo("  installed." if ok else typer.style("  install failed — see output above.", fg="red"))
+                    st = preflight.check(pid)
+                else:
+                    typer.echo(f"  skipped. Install later: {cmd}  (docs: {url})")
+            else:
+                typer.echo(f"  No package manager detected. Install manually: {typer.style(url, fg='cyan')}")
+            if not st.installed:
+                typer.echo("  → skipping auth (CLI not present). Configure later with `terraui setup`.\n")
+                continue
+
+        # 2) authenticate if needed
+        if st.authed:
+            typer.echo(typer.style(f"  ✓ already authenticated · {st.detail}\n", fg="green"))
+            continue
+
+        typer.echo(f"  Not authenticated ({st.detail}).")
+        steps = preflight.PROVIDERS[pid].login
+        if not interactive:
+            cmds = "; ".join(" ".join(a) for _, a in steps)
+            typer.echo(f"  Authenticate later by running: {cmds}\n")
+            continue
+        if not typer.confirm("  Authenticate now?", default=True):
+            cmds = "  |  ".join(" ".join(a) for _, a in steps)
+            typer.echo(f"  skipped. Authenticate later: {cmds}\n")
+            continue
+        for i, (desc, argv) in enumerate(steps):
+            typer.echo(f"  → {desc}: {typer.style(' '.join(argv), fg='cyan')}")
+            if typer.confirm("    Run this step?", default=True):
+                preflight.run_login(pid, i)
+        final = preflight.check(pid)
+        typer.echo((typer.style(f"  ✓ authenticated · {final.detail}\n", fg="green")
+                    if final.authed else typer.style("  still not authenticated — re-run when ready.\n", fg="yellow")))
+
+    typer.echo("Setup complete. Skipped providers can be configured anytime with `terraui setup`.\n")
+
+
+@app.command()
+def setup(
+    path: Optional[Path] = typer.Argument(None, help="IaC root — limits setup to the clouds your stacks use."),
+    providers: Optional[str] = typer.Option(None, "--providers", help="Comma list to configure: aws,gcp,azure."),
+    yes: bool = typer.Option(False, "--yes", help="Non-interactive: install where possible, skip browser logins."),
+):
+    """Detect, install and authenticate the cloud SDKs (gcloud/aws/az). Per-provider, skippable."""
+    if providers:
+        ids = [p.strip() for p in providers.split(",") if p.strip() in ("aws", "gcp", "azure")]
+    else:
+        ids = []
+        try:
+            from .discovery import scan_roots
+
+            stacks = [s.model_dump() for s in scan_roots([path or Path.cwd()])]
+            ids = _clouds_from_stacks(stacks)
+        except Exception:
+            ids = []
+        if not ids:
+            ids = ["aws", "gcp", "azure"]
+    _interactive_setup(ids, assume_yes=yes)
+
+
+@app.command()
+def start(
+    path: Optional[Path] = typer.Argument(None, help="IaC root to scan (default: cwd)."),
+    port: int = typer.Option(8787, help="Port to serve on."),
+    host: str = typer.Option("127.0.0.1", help="Bind address (local mode: localhost)."),
+    scan: list[Path] = typer.Option(None, "--scan", help="Extra roots/globs to scan."),
+    no_open: bool = typer.Option(False, "--no-open", help="Do not auto-open the browser."),
+    shell: Optional[str] = typer.Option(None, "--shell", help="Executor shell: powershell|pwsh|zsh|bash."),
+    drift_interval: str = typer.Option("30m", "--drift-interval", help="Background drift cadence (0 = off)."),
+    demo: bool = typer.Option(False, "--demo", help="Force the bundled demo dataset."),
+    check: bool = typer.Option(False, "--check", help="Run interactive cloud-SDK setup before serving."),
+    skip_checks: bool = typer.Option(False, "--skip-checks", help="Skip the cloud-SDK status check."),
+):
+    """Local mode: scan PATH, serve the UI + executor on http://host:port."""
+    import uvicorn
+
+    from .server.app import Config, create_app
+
+    roots = [p for p in ([path] if path else []) + list(scan or []) if p]
+    if not roots:
+        roots = [Path.cwd()]
+    cfg = Config(scan_roots=[Path(r) for r in roots], shell=shell, demo=demo,
+                 drift_interval_min=_parse_minutes(drift_interval))
+
+    app_obj = create_app(cfg)
+    state = app_obj.state.terraui
+    needed = [] if state.demo else _clouds_from_stacks(state.stacks)
+
+    if check and needed:
+        _interactive_setup(needed)
+    elif not skip_checks and needed:
+        _quick_check(needed)
+
+    url = f"http://{host}:{port}"
+    mode = "demo dataset" if state.demo else f"{len(state.stacks)} unit(s) discovered"
+    typer.echo(f"TerraUi {__version__} · {mode} · {url}")
+    if not no_open:
+        threading.Thread(target=lambda: (time.sleep(1.0), webbrowser.open(url)), daemon=True).start()
+    uvicorn.run(app_obj, host=host, port=port, log_level="warning")
+
+
+@app.command()
+def scan(
+    path: Optional[Path] = typer.Argument(None, help="IaC root to scan (default: cwd)."),
+    as_json: bool = typer.Option(False, "--json", help="Print discovered units as JSON."),
+):
+    """Discover units and print them (no server) — for CI / debugging."""
+    from .discovery import scan_roots
+
+    root = path or Path.cwd()
+    stacks = scan_roots([root])
+    if as_json:
+        typer.echo(json.dumps([s.model_dump() for s in stacks], indent=2))
+        return
+    if not stacks:
+        typer.echo(f"No Terraform/Terragrunt units found under {root}")
+        return
+    typer.echo(f"Discovered {len(stacks)} unit(s) under {root}:")
+    for s in stacks:
+        deps = f"  deps: {', '.join(s.deps)}" if s.deps else ""
+        typer.echo(f"  {s.tool:10} {s.env:8} {s.path}  [{','.join(s.clouds) or '?'}]{deps}")
+
+
+@app.command()
+def server(
+    config: Optional[Path] = typer.Option(None, "--config", help="terraui.yaml (team mode)."),
+    port: int = typer.Option(8787),
+    host: str = typer.Option("0.0.0.0"),
+):
+    """Team mode: shared control plane (SSO/RBAC/Postgres). [scaffold]"""
+    typer.echo("Server mode is scaffolded — see BACKEND_SPEC §11. Use `terraui start` for local mode.")
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def agent(
+    server_url: str = typer.Option(..., "--server", help="Control-plane URL to register with."),
+    label: str = typer.Option("runner", "--label", help="Agent label, e.g. prod-runner."),
+):
+    """Remote executor that registers with a server. [scaffold]"""
+    typer.echo(f"Agent mode is scaffolded — would register '{label}' with {server_url}. See BACKEND_SPEC §11.")
+    raise typer.Exit(code=1)
+
+
+def _parse_minutes(value: str) -> int:
+    value = (value or "0").strip().lower()
+    if value in ("0", "off", ""):
+        return 0
+    if value.endswith("m"):
+        return int(value[:-1] or 0)
+    if value.endswith("h"):
+        return int(value[:-1] or 0) * 60
+    return int(value)
+
+
+if __name__ == "__main__":
+    app()

terraui/clouds/auth.py

@@ -0,0 +1,76 @@
+"""Cloud SDK auth detection (BACKEND_SPEC §7).
+
+Read-only probes per cloud, cached ~60s. GCP requires BOTH a user login and ADC.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+
+from ..execution.executor import run_capture
+from ..models import CloudAuth
+
+_CACHE: dict[str, tuple[float, CloudAuth]] = {}
+_TTL = 60.0
+
+
+async def _aws() -> CloudAuth:
+    code, out = await run_capture(["aws", "sts", "get-caller-identity", "--output", "json"])
+    name, cli = "AWS", await _version("aws", "--version")
+    if code == 0:
+        try:
+            data = json.loads(out)
+            acct, arn = data.get("Account", ""), data.get("Arn", "")
+            return CloudAuth(id="aws", name=name, cli=cli, ok=True, status="authenticated", detail=f"{acct} · {arn}")
+        except json.JSONDecodeError:
+            pass
+    return CloudAuth(id="aws", name=name, cli=cli, ok=False, status="re-auth", detail="not authenticated · aws sso login")
+
+
+async def _gcp() -> CloudAuth:
+    cli = await _version("gcloud", "--version")
+    adc_code, _ = await run_capture(["gcloud", "auth", "application-default", "print-access-token"])
+    list_code, list_out = await run_capture(["gcloud", "auth", "list", "--format=value(account)"])
+    active = [ln for ln in list_out.splitlines() if ln.strip()]
+    if adc_code == 0 and list_code == 0 and active:
+        return CloudAuth(id="gcp", name="GCP", cli=cli, ok=True, status="authenticated", detail=f"{active[0]} · ADC active")
+    if list_code == 0 and active and adc_code != 0:
+        return CloudAuth(id="gcp", name="GCP", cli=cli, ok=False, status="re-auth", detail="run gcloud auth application-default login")
+    return CloudAuth(id="gcp", name="GCP", cli=cli, ok=False, status="re-auth", detail="run gcloud auth login")
+
+
+async def _azure() -> CloudAuth:
+    cli = await _version("az", "version")
+    code, out = await run_capture(["az", "account", "show", "--output", "json"])
+    if code == 0:
+        try:
+            data = json.loads(out)
+            return CloudAuth(id="azure", name="Azure", cli=cli, ok=True, status="authenticated", detail=f"{data.get('name','')} · {data.get('id','')}")
+        except json.JSONDecodeError:
+            pass
+    return CloudAuth(id="azure", name="Azure", cli=cli, ok=False, status="re-auth", detail="token expired · run az login")
+
+
+async def _version(exe: str, *args: str) -> str:
+    code, out = await run_capture([exe, *args], timeout=10)
+    if code != 0:
+        return f"{exe} (not found)"
+    m = re.search(r"(\d+\.\d+(?:\.\d+)?)", out)
+    return f"{exe} {m.group(1)}" if m else exe
+
+
+async def probe_all(force: bool = False) -> list[CloudAuth]:
+    now = time.time()
+    results: list[CloudAuth] = []
+    probes = {"aws": _aws, "gcp": _gcp, "azure": _azure}
+    for cid, fn in probes.items():
+        cached = _CACHE.get(cid)
+        if not force and cached and now - cached[0] < _TTL:
+            results.append(cached[1])
+            continue
+        auth = await fn()
+        _CACHE[cid] = (now, auth)
+        results.append(auth)
+    return results

terraui/clouds/preflight.py

@@ -0,0 +1,192 @@
+"""Cloud SDK preflight — detect, (optionally) install, and authenticate the
+provider CLIs TerraUi shells out to (BACKEND_SPEC §7).
+
+Read-only by default: detection runs `--version` and the auth probes only. Any
+state-changing step (installing a CLI, running a login) is shown as the exact
+command and gated behind explicit per-provider confirmation. Nothing is stored;
+auth uses each SDK's own credential flow. Providers can be skipped and configured
+later — a GCP-only user need not touch AWS/Azure.
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+IS_WIN = platform.system() == "Windows"
+IS_MAC = platform.system() == "Darwin"
+
+
+# ---- injectable primitives (monkeypatched in tests; never run installs there) ----
+def _which(exe: str) -> Optional[str]:
+    return shutil.which(exe)
+
+
+def _run(argv: list[str], timeout: float = 15, interactive: bool = False) -> tuple[int, str]:
+    """Run a command. interactive=True inherits the terminal (for logins/installs)."""
+    try:
+        if interactive:
+            return subprocess.run(argv).returncode or 0, ""
+        p = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+        return p.returncode, (p.stdout or "") + (p.stderr or "")
+    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        return 127, str(exc)
+
+
+def package_managers() -> list[str]:
+    """Available package managers on this machine, in preference order."""
+    candidates = ["winget", "choco", "scoop"] if IS_WIN else (["brew"] if IS_MAC else ["brew", "apt-get", "dnf"])
+    return [pm for pm in candidates if _which(pm)]
+
+
+@dataclass
+class Provider:
+    id: str               # aws | gcp | azure
+    name: str             # AWS | GCP | Azure
+    exe: str              # aws | gcloud | az
+    docs_url: str
+    install: dict = field(default_factory=dict)   # pkg-manager -> argv
+    install_url: str = ""                          # manual installer link
+    login: list = field(default_factory=list)      # [(description, argv), ...]
+
+
+PROVIDERS: dict[str, Provider] = {
+    "aws": Provider(
+        id="aws", name="AWS", exe="aws",
+        docs_url="https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html",
+        install={
+            "winget": ["winget", "install", "-e", "--id", "Amazon.AWSCLI", "--accept-source-agreements", "--accept-package-agreements"],
+            "choco": ["choco", "install", "awscli", "-y"],
+            "brew": ["brew", "install", "awscli"],
+        },
+        install_url="https://awscli.amazonaws.com/AWSCLIV2.msi" if IS_WIN else "https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html",
+        login=[
+            ("Sign in with AWS IAM Identity Center (SSO)", ["aws", "configure", "sso"]),
+            ("Configure static access keys", ["aws", "configure"]),
+        ],
+    ),
+    "gcp": Provider(
+        id="gcp", name="GCP", exe="gcloud",
+        docs_url="https://cloud.google.com/sdk/docs/install",
+        install={
+            "winget": ["winget", "install", "-e", "--id", "Google.CloudSDK", "--accept-source-agreements", "--accept-package-agreements"],
+            "choco": ["choco", "install", "gcloudsdk", "-y"],
+            "brew": ["brew", "install", "--cask", "google-cloud-sdk"],
+        },
+        install_url="https://cloud.google.com/sdk/docs/install",
+        # both are required: user login for the gcloud CLI, ADC for the Terraform google provider
+        login=[
+            ("gcloud user login (CLI identity)", ["gcloud", "auth", "login"]),
+            ("Application Default Credentials (used by Terraform)", ["gcloud", "auth", "application-default", "login"]),
+        ],
+    ),
+    "azure": Provider(
+        id="azure", name="Azure", exe="az",
+        docs_url="https://learn.microsoft.com/cli/azure/install-azure-cli",
+        install={
+            "winget": ["winget", "install", "-e", "--id", "Microsoft.AzureCLI", "--accept-source-agreements", "--accept-package-agreements"],
+            "choco": ["choco", "install", "azure-cli", "-y"],
+            "brew": ["brew", "install", "azure-cli"],
+        },
+        install_url="https://aka.ms/installazurecliwindows" if IS_WIN else "https://learn.microsoft.com/cli/azure/install-azure-cli",
+        login=[("az login (opens browser)", ["az", "login"])],
+    ),
+}
+
+
+@dataclass
+class Status:
+    id: str
+    name: str
+    installed: bool = False
+    version: str = ""
+    authed: bool = False
+    detail: str = ""
+
+
+def _version(p: Provider) -> str:
+    args = ["version"] if p.id == "azure" else ["--version"]
+    code, out = _run([p.exe, *args], timeout=10)
+    if code == 127:
+        return ""
+    m = re.search(r"(\d+\.\d+(?:\.\d+)?)", out)
+    return f"{p.exe} {m.group(1)}" if m else p.exe
+
+
+def _auth(p: Provider) -> tuple[bool, str]:
+    if p.id == "aws":
+        code, out = _run([p.exe, "sts", "get-caller-identity", "--output", "json"])
+        if code == 0:
+            try:
+                d = json.loads(out)
+                return True, f"{d.get('Account','')} · {d.get('Arn','')}"
+            except json.JSONDecodeError:
+                pass
+        return False, "not authenticated · aws sso login"
+    if p.id == "gcp":
+        adc, _ = _run([p.exe, "auth", "application-default", "print-access-token"])
+        lst, out = _run([p.exe, "auth", "list", "--format=value(account)"])
+        accts = [x for x in out.splitlines() if x.strip()]
+        if adc == 0 and lst == 0 and accts:
+            return True, f"{accts[0]} · ADC active"
+        if accts:
+            return False, "ADC missing · gcloud auth application-default login"
+        return False, "not authenticated · gcloud auth login"
+    # azure
+    code, out = _run([p.exe, "account", "show", "--output", "json"])
+    if code == 0:
+        try:
+            d = json.loads(out)
+            return True, f"{d.get('name','')} · {d.get('id','')}"
+        except json.JSONDecodeError:
+            pass
+    return False, "token expired · az login"
+
+
+def check(provider_id: str) -> Status:
+    """Read-only status for one provider."""
+    p = PROVIDERS[provider_id]
+    st = Status(id=p.id, name=p.name)
+    if not _which(p.exe):
+        st.detail = "CLI not installed"
+        return st
+    st.installed = True
+    st.version = _version(p)
+    st.authed, st.detail = _auth(p)
+    return st
+
+
+def check_all(provider_ids: Optional[list[str]] = None) -> list[Status]:
+    return [check(pid) for pid in (provider_ids or list(PROVIDERS))]
+
+
+def install_command(provider_id: str) -> tuple[Optional[list[str]], str]:
+    """Best install argv for this machine + the manual-install URL."""
+    p = PROVIDERS[provider_id]
+    for pm in package_managers():
+        if pm in p.install:
+            return p.install[pm], p.install_url
+    return None, p.install_url
+
+
+# ---- interactive driver (used by `terraui setup`) ----
+def run_install(provider_id: str) -> bool:
+    argv, url = install_command(provider_id)
+    if not argv:
+        return False
+    code, _ = _run(argv, interactive=True, timeout=900)
+    return code == 0
+
+
+def run_login(provider_id: str, step_index: int) -> bool:
+    p = PROVIDERS[provider_id]
+    if step_index >= len(p.login):
+        return False
+    _, argv = p.login[step_index]
+    code, _ = _run(argv, interactive=True, timeout=900)
+    return code == 0