openhack 0.1.0__py3-none-any.whl

openhack/scan_session.py

@@ -0,0 +1,245 @@
+"""
+Scan session — tracks which entry points have been analyzed across runs.
+
+Provides resume capability: start a scan, stop partway, resume later from
+where you left off. Each session has a unique ID and persists to disk.
+"""
+
+import json
+import logging
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+SESSIONS_DIR = Path.home() / ".openhack" / "scans"
+SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+class ScanSession:
+    """Tracks scan progress across entry points."""
+
+    def __init__(self, session_id: str, target_dir: str):
+        self.session_id = session_id
+        self.target_dir = target_dir
+        self.created_at = datetime.now().isoformat()
+        self.updated_at = self.created_at
+        self.classifications = []  # Framework classifications
+        self.entry_points = []     # All detected entry points
+        self.findings = []         # Findings from scanned entry points
+        self.total_cost = 0.0
+        self.attack_surface: Optional[dict] = None
+        self.analyzed_files: list[str] = []
+        self.zone_coverage: dict[str, dict] = {}  # zone_name -> {status, files_total, files_done}
+
+    @property
+    def scanned_count(self) -> int:
+        return sum(1 for ep in self.entry_points if ep.get("status") != "unscanned")
+
+    @property
+    def unscanned_count(self) -> int:
+        return sum(1 for ep in self.entry_points if ep.get("status") == "unscanned")
+
+    @property
+    def coverage_pct(self) -> float:
+        total = len(self.entry_points)
+        if total == 0:
+            return 0.0
+        return (self.scanned_count / total) * 100
+
+    def mark_scanned(self, file_path: str, status: str = "scanned"):
+        """Mark all entry points in a file as scanned."""
+        for ep in self.entry_points:
+            if ep.get("file") == file_path:
+                ep["status"] = status
+        self.updated_at = datetime.now().isoformat()
+
+    def mark_finding(self, file_path: str):
+        """Mark entry points in a file as having findings."""
+        for ep in self.entry_points:
+            if ep.get("file") == file_path:
+                ep["status"] = "finding_found"
+        self.updated_at = datetime.now().isoformat()
+
+    def get_unscanned_files(self) -> list[str]:
+        """Get list of unique files with unscanned entry points."""
+        files = set()
+        for ep in self.entry_points:
+            if ep.get("status") == "unscanned":
+                files.add(ep.get("file", ""))
+        return sorted(files)
+
+    def get_scanned_files(self) -> list[str]:
+        """Get list of files that have been scanned."""
+        files = set()
+        for ep in self.entry_points:
+            if ep.get("status") != "unscanned":
+                files.add(ep.get("file", ""))
+        return sorted(files)
+
+    def mark_zone_complete(self, zone_name: str, files_analyzed: list[str], findings_count: int = 0):
+        """Mark a zone as completed after a researcher finishes."""
+        self.zone_coverage[zone_name] = {
+            "status": "completed",
+            "files_analyzed": files_analyzed,
+            "files_done": len(files_analyzed),
+            "findings_count": findings_count,
+            "completed_at": datetime.now().isoformat(),
+        }
+        for f in files_analyzed:
+            if f not in self.analyzed_files:
+                self.analyzed_files.append(f)
+        self.updated_at = datetime.now().isoformat()
+
+    def get_completed_zones(self) -> set[str]:
+        """Get names of zones that have been fully analyzed."""
+        return {
+            name for name, info in self.zone_coverage.items()
+            if info.get("status") == "completed"
+        }
+
+    def get_analyzed_file_set(self) -> set[str]:
+        """Get all files that have been analyzed across all zones."""
+        return set(self.analyzed_files)
+
+    def save(self):
+        """Persist session to disk."""
+        path = SESSIONS_DIR / f"{self.session_id}.json"
+        data = {
+            "session_id": self.session_id,
+            "target_dir": self.target_dir,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "classifications": self.classifications,
+            "entry_points": self.entry_points,
+            "findings": self.findings,
+            "total_cost": self.total_cost,
+            "attack_surface": self.attack_surface,
+            "analyzed_files": self.analyzed_files,
+            "zone_coverage": self.zone_coverage,
+            "stats": {
+                "total": len(self.entry_points),
+                "scanned": self.scanned_count,
+                "unscanned": self.unscanned_count,
+                "coverage_pct": round(self.coverage_pct, 1),
+                "findings_count": len(self.findings),
+                "zones_completed": len(self.get_completed_zones()),
+                "files_analyzed": len(self.analyzed_files),
+            },
+        }
+        path.write_text(json.dumps(data, indent=2, default=str))
+        logger.debug(f"Session {self.session_id} saved: {self.scanned_count}/{len(self.entry_points)} scanned")
+
+    @classmethod
+    def load(cls, session_id: str) -> Optional["ScanSession"]:
+        """Load a session from disk."""
+        path = SESSIONS_DIR / f"{session_id}.json"
+        if not path.exists():
+            return None
+        data = json.loads(path.read_text())
+        session = cls(data["session_id"], data["target_dir"])
+        session.created_at = data.get("created_at", "")
+        session.updated_at = data.get("updated_at", "")
+        session.classifications = data.get("classifications", [])
+        session.entry_points = data.get("entry_points", [])
+        session.findings = data.get("findings", [])
+        session.total_cost = data.get("total_cost", 0.0)
+        session.attack_surface = data.get("attack_surface")
+        session.analyzed_files = data.get("analyzed_files", [])
+        session.zone_coverage = data.get("zone_coverage", {})
+        return session
+
+    @classmethod
+    def list_sessions(cls, target_dir: Optional[str] = None) -> list[dict]:
+        """List all saved sessions, optionally filtered by target_dir."""
+        sessions = []
+        for path in sorted(SESSIONS_DIR.glob("*.json"), reverse=True):
+            try:
+                data = json.loads(path.read_text())
+                if target_dir and data.get("target_dir") != target_dir:
+                    continue
+                sessions.append({
+                    "session_id": data["session_id"],
+                    "target_dir": data.get("target_dir", "?"),
+                    "created_at": data.get("created_at", "?"),
+                    "stats": data.get("stats", {}),
+                })
+            except Exception:
+                continue
+        return sessions
+
+    def print_summary(self):
+        """Print a human-readable summary of the session."""
+        print(f"\n{'='*60}")
+        print(f"  Scan Session: {self.session_id}")
+        print(f"  Target: {self.target_dir}")
+        print(f"  Created: {self.created_at}")
+        print(f"{'='*60}")
+
+        # Framework summary
+        if self.classifications:
+            print(f"\n  Frameworks:")
+            for c in self.classifications:
+                print(f"    {c['root']} → {c['language']} [{', '.join(c['frameworks'])}]")
+
+        # Entry point summary
+        total = len(self.entry_points)
+        scanned = self.scanned_count
+        unscanned = self.unscanned_count
+        with_findings = sum(1 for ep in self.entry_points if ep.get("status") == "finding_found")
+
+        print(f"\n  Entry Points: {total}")
+        print(f"    Scanned:    {scanned} ({self.coverage_pct:.1f}%)")
+        print(f"    Unscanned:  {unscanned}")
+        print(f"    w/ Findings: {with_findings}")
+
+        # Zone coverage
+        if self.zone_coverage:
+            completed = self.get_completed_zones()
+            print(f"\n  Zones: {len(completed)} completed")
+            for name, info in self.zone_coverage.items():
+                status = info.get("status", "?")
+                done = info.get("files_done", 0)
+                findings = info.get("findings_count", 0)
+                icon = "[✓]" if status == "completed" else "[ ]"
+                print(f"    {icon} {name} — {done} files, {findings} findings")
+
+        if self.analyzed_files:
+            print(f"\n  Files Analyzed: {len(self.analyzed_files)}")
+
+        # Findings summary
+        if self.findings:
+            print(f"\n  Findings: {len(self.findings)}")
+            for f in self.findings:
+                sev = f.get("severity", "?").upper()
+                cat = f.get("category", "?")
+                fp = f.get("file_path", "?")
+                print(f"    [{sev}] {cat} — {fp}")
+
+        print(f"\n  Cost: ${self.total_cost:.4f}")
+        print()
+
+    def print_entry_points(self, show_all: bool = False):
+        """Print all entry points with their scan status."""
+        print(f"\n  {'Status':<15} {'Method':<10} {'Path':<50} {'File'}")
+        print(f"  {'-'*100}")
+        for ep in self.entry_points:
+            status = ep.get("status", "unscanned")
+            if not show_all and status != "unscanned":
+                continue
+            status_icon = {
+                "unscanned": "[ ]",
+                "scanned": "[✓]",
+                "finding_found": "[!]",
+                "clean": "[·]",
+            }.get(status, "[?]")
+            method = ep.get("method", "?")
+            path = ep.get("path", "?")
+            file = ep.get("file", "?")
+            # Truncate long paths
+            if len(path) > 48:
+                path = path[:45] + "..."
+            print(f"  {status_icon:<15} {method:<10} {path:<50} {file}")

openhack/setup.py

@@ -0,0 +1,452 @@
+"""
+Interactive configuration wizard for OpenHack.
+
+Two entry points:
+  - run_first_time_setup()  — auto-launched when ~/.openhack/config is absent
+  - run_setup_command()     — triggered by /setup inside the TUI (async)
+
+Uses prompt_toolkit for arrow-key driven selection menus, secure password
+input for API keys, and a final confirmation screen.
+"""
+
+import asyncio
+import getpass
+import os
+from typing import Optional
+
+from prompt_toolkit import print_formatted_text
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.application import Application
+from prompt_toolkit.layout.containers import HSplit, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+from prompt_toolkit.layout.layout import Layout
+
+from openhack.auth import (
+    DeviceLoginCancelled,
+    DeviceLoginError,
+    DeviceLoginExpired,
+    device_login,
+)
+from openhack.config import (
+    CONFIG_PATH,
+    load_user_config,
+    save_user_config,
+    resolve_provider,
+    reload_settings,
+    settings,
+)
+
+DIM = '<style fg="ansigray">'
+EDIM = '</style>'
+B = '<b>'
+EB = '</b>'
+CYAN = '<ansicyan>'
+ECYAN = '</ansicyan>'
+GREEN = '<ansigreen>'
+EGREEN = '</ansigreen>'
+YELLOW = '<ansiyellow>'
+EYELLOW = '</ansiyellow>'
+
+
+def _html(text: str) -> None:
+    print_formatted_text(HTML(text))
+
+
+def _esc(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _clear() -> None:
+    print("\033[2J\033[H", end="", flush=True)
+
+
+# ── Provider / model definitions ──────────────────────────────────
+
+PROVIDERS = [
+    {
+        "key": "openhack",
+        "display": "OpenHack",
+        "hint": "Recommended — no setup required, free tier available",
+        "key_field": "openhack_api_key",
+        "key_env": "OPENHACK_API_KEY",
+        # key_url is built dynamically from settings.openhack_app_url at display time.
+        "models": [
+            ("kimi-k2.5", "Kimi K2.5", "Flagship security analysis model"),
+        ],
+        "default_model": "kimi-k2.5",
+    },
+]
+
+
+def _mask_key(key: str) -> str:
+    if not key:
+        return "(not set)"
+    if len(key) <= 12:
+        return key[:2] + "•" * (len(key) - 2)
+    return key[:6] + "•" * 8 + key[-4:]
+
+def _has_running_loop() -> bool:
+    try:
+        loop = asyncio.get_running_loop()
+        return loop.is_running()
+    except RuntimeError:
+        return False
+
+
+# ── Arrow-key selection menu ──────────────────────────────────────
+
+async def _select_menu_async(title: str, items: list[tuple[str, str, str]], default_idx: int = 0) -> int:
+    """Render an arrow-key driven selection menu. Returns the chosen index.
+
+    items: list of (value, label, hint)
+    """
+    selected = [default_idx]
+
+    def _get_text():
+        lines = []
+        lines.append(("class:title", f"  {title}\n\n"))
+        for i, (_, label, hint) in enumerate(items):
+            if i == selected[0]:
+                lines.append(("class:selected", f"  ❯ {label}"))
+                if hint:
+                    lines.append(("class:hint.selected", f"  {hint}"))
+                lines.append(("", "\n"))
+            else:
+                lines.append(("class:unselected", f"    {label}"))
+                if hint:
+                    lines.append(("class:hint", f"  {hint}"))
+                lines.append(("", "\n"))
+        lines.append(("class:footer", "\n  ↑/↓ to move · Enter to select · q to cancel"))
+        return lines
+
+    kb = KeyBindings()
+    result = [None]
+
+    @kb.add("up")
+    @kb.add("k")
+    def _up(event):
+        selected[0] = (selected[0] - 1) % len(items)
+
+    @kb.add("down")
+    @kb.add("j")
+    def _down(event):
+        selected[0] = (selected[0] + 1) % len(items)
+
+    @kb.add("enter")
+    def _enter(event):
+        result[0] = selected[0]
+        event.app.exit()
+
+    @kb.add("q")
+    @kb.add("escape")
+    def _quit(event):
+        result[0] = -1
+        event.app.exit()
+
+    from prompt_toolkit.styles import Style
+    style = Style.from_dict({
+        "title": "bold",
+        "selected": "bold ansibrightcyan",
+        "hint.selected": "ansigray",
+        "unselected": "",
+        "hint": "ansigray",
+        "footer": "ansigray italic",
+    })
+
+    control = FormattedTextControl(_get_text)
+    window = Window(content=control, always_hide_cursor=True)
+    layout = Layout(HSplit([window]))
+    app = Application(layout=layout, key_bindings=kb, style=style, full_screen=False)
+    await app.run_async()
+
+    return result[0] if result[0] is not None else -1
+
+
+def _select_menu(title: str, items: list[tuple[str, str, str]], default_idx: int = 0) -> int:
+    """Sync wrapper — delegates to async impl."""
+    if _has_running_loop():
+        raise RuntimeError("Use _select_menu_async from within an event loop")
+
+    return asyncio.run(_select_menu_async(title, items, default_idx))
+
+
+# ── API key input ─────────────────────────────────────────────────
+
+def _prompt_api_key(provider: dict, existing_key: Optional[str] = None) -> Optional[str]:
+    """Prompt for an API key with masked display."""
+    _html("")
+    _html(f'  {B}API Key for {_esc(provider["display"])}{EB}')
+    key_url = f"{settings.openhack_app_url.rstrip('/')}/settings/api-keys"
+    _html(f'  {DIM}Get your key at: {_esc(key_url)}{EDIM}')
+    _html("")
+
+    if existing_key:
+        _html(f'  {DIM}Current: {_esc(_mask_key(existing_key))}{EDIM}')
+        _html(f'  {DIM}Press Enter to keep existing key, or paste a new one{EDIM}')
+        _html("")
+
+    env_val = os.environ.get(provider["key_env"])
+    if env_val:
+        _html(f'  {DIM}Found in environment: ${_esc(provider["key_env"])} = {_esc(_mask_key(env_val))}{EDIM}')
+        _html(f'  {DIM}Press Enter to use environment value{EDIM}')
+        _html("")
+
+    try:
+        key = getpass.getpass("  API Key: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        return existing_key
+
+    if not key:
+        if existing_key:
+            return existing_key
+        if env_val:
+            return env_val
+        return None
+
+    return key
+
+
+# ── Base URL input (for OpenHack provider) ───────────────────────────
+
+def _prompt_base_url(existing: Optional[str] = None) -> str:
+    if not existing:
+        existing = settings.openhack_base_url
+    _html("")
+    _html(f'  {B}OpenHack Base URL{EB}')
+    _html(f'  {DIM}Default: {_esc(existing)}{EDIM}')
+    _html(f'  {DIM}Press Enter to keep default{EDIM}')
+    _html("")
+    try:
+        url = input("  Base URL: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        return existing
+    return url if url else existing
+
+
+# ── Summary / confirmation ────────────────────────────────────────
+
+def _show_summary(provider: dict, model_id: str, api_key: Optional[str], base_url: Optional[str] = None, org_name: Optional[str] = None) -> bool:
+    _html("")
+    _html(f'  {"━" * 50}')
+    _html(f'  {B}Configuration Summary{EB}')
+    _html(f'  {"━" * 50}')
+    _html("")
+    _html(f'  {B}Provider:{EB}  {_esc(provider["display"])}')
+    if org_name:
+        _html(f'  {B}Org:{EB}       {_esc(org_name)}')
+    _html(f'  {B}Model:{EB}     {_esc(model_id)}')
+    _html(f'  {B}API Key:{EB}   {_esc(_mask_key(api_key or ""))}')
+    if base_url and provider["key"] == "openhack":
+        _html(f'  {B}Base URL:{EB}  {_esc(base_url)}')
+    _html("")
+    _html(f'  {DIM}Config will be saved to {_esc(str(CONFIG_PATH))}{EDIM}')
+    _html("")
+
+    try:
+        confirm = input("  Save this configuration? [Y/n] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return False
+
+    return confirm in ("", "y", "yes")
+
+
+# ── First-time setup wizard ──────────────────────────────────────
+
+def _banner() -> None:
+    _html("")
+    _html(f'  <b><ansibrightwhite>            ██</ansibrightwhite></b>')
+    _html(f'  <b><ansibrightwhite>            ██</ansibrightwhite></b>')
+    _html(f'  <b><ansibrightwhite>            ██</ansibrightwhite></b>')
+    _html(f'  <b><ansibrightwhite>     ████████████████</ansibrightwhite></b>')
+    _html("")
+    _html(f'  <b><ansibrightwhite>       ████████████</ansibrightwhite></b>')
+    _html("")
+    _html(f'  <b><ansibrightwhite>         ████████</ansibrightwhite></b>')
+    _html("")
+    _html(f'  <b><ansicyan>  OpenHack</ansicyan></b> — First Time Setup')
+    _html("")
+    _html(f'  {DIM}Welcome to OpenHack! Let\'s get started with setup.{EDIM}')
+    _html("")
+
+
+def _setup_banner() -> None:
+    _html("")
+    _html(f'  <b><ansibrightwhite>            ██</ansibrightwhite></b>')
+    _html(f'  <b><ansibrightwhite>            ██</ansibrightwhite></b>')
+    _html(f'  <b><ansibrightwhite>            ██</ansibrightwhite></b>')
+    _html(f'  <b><ansibrightwhite>     ████████████████</ansibrightwhite></b>')
+    _html("")
+    _html(f'  <b><ansibrightwhite>       ████████████</ansibrightwhite></b>')
+    _html("")
+    _html(f'  <b><ansibrightwhite>         ████████</ansibrightwhite></b>')
+    _html("")
+    _html(f'  <b><ansicyan>  OpenHack</ansicyan></b> — Configuration')
+    _html("")
+    _html(f'  {DIM}Update your settings and API key.{EDIM}')
+    _html("")
+
+
+async def _run_wizard(is_first_time: bool = True) -> bool:
+    """Run the interactive configuration wizard. Returns True if config was saved."""
+    cfg = load_user_config()
+
+    if is_first_time:
+        _banner()
+    else:
+        _setup_banner()
+
+    provider = PROVIDERS[0]
+    default_model = provider["default_model"]
+    default_base_url = cfg.get("openhack_base_url") or settings.openhack_base_url
+
+    # ── Step 1: Login / API key / Custom ─────────────────────────
+    setup_choice = await _select_menu_async(
+        "How would you like to proceed?",
+        [
+            ("login", "Login with OpenHack account", "(Recommended, free $20 credits on signup)"),
+            ("apikey", "Use OpenHack API Key", ""),
+            ("custom", "Custom setup", ""),
+        ],
+    )
+    if setup_choice < 0:
+        _html(f'  {DIM}Setup cancelled.{EDIM}')
+        _html("")
+        return False
+
+    api_key: Optional[str] = None
+    model_id = default_model
+    base_url = default_base_url
+    login_result = None
+
+    if setup_choice == 0:
+        # Browser-based device-code login.
+        app_url = cfg.get("openhack_app_url") or settings.openhack_app_url
+        try:
+            login_result = await device_login(app_url)
+            api_key = login_result.token
+        except DeviceLoginCancelled:
+            _html(f'  {DIM}Login cancelled.{EDIM}')
+            _html("")
+            return False
+        except DeviceLoginExpired as exc:
+            _html(f'  {YELLOW}⚠{EYELLOW}  {_esc(str(exc))}')
+            _html("")
+            return False
+        except DeviceLoginError as exc:
+            _html(f'  {YELLOW}⚠{EYELLOW}  Login failed: {_esc(str(exc))}')
+            _html("")
+            return False
+    elif setup_choice == 1:
+        # User pastes an existing OpenHack API token from the dashboard.
+        existing_key = cfg.get(provider["key_field"])
+        api_key = _prompt_api_key(provider, existing_key)
+        if not api_key:
+            _html("")
+            _html(f'  {YELLOW}⚠{EYELLOW}  An API key is required.')
+            _html(f'  {DIM}Sign up at: {_esc(settings.openhack_app_url)}/signup{EDIM}')
+            _html("")
+    else:
+        # Custom: pick model, base URL, paste key.
+        model_items = [
+            (m[0], m[1], m[2])
+            for m in provider["models"]
+        ]
+        current_model = cfg.get("model") or cfg.get("openhack_model_id")
+        default_model_idx = 0
+        for i, (mid, _, _) in enumerate(provider["models"]):
+            if mid == current_model:
+                default_model_idx = i
+                break
+
+        model_idx = await _select_menu_async(
+            "Choose a model:",
+            model_items,
+            default_idx=default_model_idx,
+        )
+        if model_idx < 0:
+            _html(f'  {DIM}Setup cancelled.{EDIM}')
+            _html("")
+            return False
+        model_id = provider["models"][model_idx][0]
+
+        base_url = _prompt_base_url(default_base_url)
+
+        existing_key = cfg.get(provider["key_field"])
+        api_key = _prompt_api_key(provider, existing_key)
+        if not api_key:
+            _html("")
+            _html(f'  {YELLOW}⚠{EYELLOW}  An API key is required.')
+            _html(f'  {DIM}Sign up at: {_esc(settings.openhack_app_url)}/signup{EDIM}')
+            _html("")
+
+    # ── Step 3: Summary & confirm ─────────────────────────────────
+    org_name = login_result.org_name if login_result else None
+    if not _show_summary(provider, model_id, api_key, base_url, org_name):
+        _html(f'  {DIM}Setup cancelled. No changes saved.{EDIM}')
+        _html("")
+        return False
+
+    # ── Save ──────────────────────────────────────────────────────
+    new_cfg = {
+        "provider": "openhack",
+        "model": model_id,
+        "openhack_model_id": model_id,
+    }
+    # Only persist base_url if the user explicitly customized it. Otherwise
+    # leave it out so the dev/prod default (driven by OPENHACK_DEV) wins.
+    if setup_choice == 2 and base_url and base_url != settings.openhack_base_url:
+        new_cfg["openhack_base_url"] = base_url
+    if api_key:
+        new_cfg["openhack_api_key"] = api_key
+    if login_result:
+        if login_result.org_id:
+            new_cfg["openhack_org_id"] = login_result.org_id
+        if login_result.org_slug:
+            new_cfg["openhack_org_slug"] = login_result.org_slug
+        if login_result.org_name:
+            new_cfg["openhack_org_name"] = login_result.org_name
+        if login_result.user_email:
+            new_cfg["openhack_user_email"] = login_result.user_email
+        if login_result.user_first_name:
+            new_cfg["openhack_user_first_name"] = login_result.user_first_name
+        if login_result.user_last_name:
+            new_cfg["openhack_user_last_name"] = login_result.user_last_name
+
+    save_user_config(new_cfg)
+    reload_settings()
+
+    _html("")
+    _html(f'  {GREEN}✓{EGREEN} {B}Configuration saved!{EB}')
+    _html(f'  {DIM}Stored in {_esc(str(CONFIG_PATH))}{EDIM}')
+    _html("")
+
+    return True
+
+
+def needs_first_time_setup() -> bool:
+    """Check if this is a first-time run (no config file exists)."""
+    if not CONFIG_PATH.exists():
+        return True
+    cfg = load_user_config()
+    if not cfg:
+        return True
+    has_provider = cfg.get("provider")
+    if not has_provider:
+        return True
+    # All providers now require an API key
+    has_any_key = any(
+        cfg.get(p["key_field"])
+        for p in PROVIDERS
+    )
+    return not has_any_key
+
+
+def run_first_time_setup() -> bool:
+    """Run the first-time setup wizard. Returns True if setup completed."""
+    return asyncio.run(_run_wizard(is_first_time=True))
+
+
+async def run_setup_command() -> bool:
+    """Run the /setup configuration wizard (async, for use inside TUI). Returns True if config was saved."""
+    return await _run_wizard(is_first_time=False)