ltcai 11.2.0 → 11.4.0

package/latticeai/setup/wizard/install.py

@@ -0,0 +1,348 @@
+"""Verification, repair, and the SSE install stream.
+
+The acting half of the wizard: prove a binary or module is really there, try a
+bounded automatic repair when it is not, and stream one SSE event per step
+while pip/brew/model-load/auth actions run. Every subprocess goes through the
+process-audit command plan, and every plan is confirmed against the token the
+caller returned.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import time
+from typing import Any, AsyncIterator, Dict, List, Tuple
+
+from latticeai.core.quiet import quiet
+from latticeai.services.process_audit import (
+    CommandConfirmationError,
+    append_process_audit_event,
+    command_plan,
+    require_command_confirmation,
+)
+from latticeai.setup.wizard.paths import (
+    _module_available,
+    _package_module,
+    _which_any,
+    repair_path_for,
+)
+from latticeai.setup.wizard.plans import _sse, _verify_action_confirmation
+
+
+def _verify_binary(binary: str, version_args: List[str] | None = None, timeout: int = 20) -> Tuple[bool, str]:
+    repair_path_for(binary)
+    found = _which_any(binary)
+    if not found:
+        return False, f"{binary} 실행 파일을 PATH에서 찾지 못했습니다."
+    args = [found, *(version_args or ["--version"])]
+    try:
+        completed = subprocess.run(args, capture_output=True, text=True, timeout=timeout, check=False)
+    except Exception as e:
+        return False, str(e)
+    output = (completed.stdout or completed.stderr or "").strip().splitlines()
+    if completed.returncode == 0:
+        return True, output[0] if output else found
+    return False, (completed.stderr or completed.stdout or f"returncode={completed.returncode}")[-400:]
+
+
+async def _wait_for_binary(binary: str, seconds: int = 300) -> Tuple[bool, str]:
+    deadline = time.time() + seconds
+    while time.time() < deadline:
+        ok, msg = _verify_binary(binary)
+        if ok:
+            return True, msg
+        await asyncio.sleep(2)
+    return False, f"{binary} 설치 완료를 제한 시간 안에 감지하지 못했습니다."
+
+# ── Installation Stream ───────────────────────────────────────────────────────
+
+def _verify_action(action: Dict[str, Any]) -> Tuple[bool, str]:
+    atype = action.get("type")
+    if atype == "pip":
+        modules = action.get("verify_modules") or [_package_module(pkg) for pkg in action.get("packages", [])]
+        missing = [module for module in modules if not _module_available(module)]
+        if missing:
+            return False, "Python 모듈 감지 실패: " + ", ".join(missing)
+        return True, "Python 모듈 import 테스트 통과"
+    binary = action.get("binary")
+    if binary:
+        return _verify_binary(binary)
+    return True, "검증 항목 없음"
+
+
+async def _repair_action(
+    action: Dict[str, Any],
+    *,
+    confirmation_token: str | None = None,
+    actor: str | None = None,
+) -> Tuple[bool, str]:
+    binary = action.get("binary")
+    if binary:
+        repair_path_for(binary)
+        ok, msg = _verify_binary(binary)
+        if ok:
+            return True, f"PATH 자동 보정 완료: {msg}"
+    if action.get("type") == "pip":
+        packages = action.get("packages", [])
+        if packages:
+            if not _verify_action_confirmation(action, confirmation_token, name="repair_action"):
+                return False, "설치 명령 확인 토큰이 일치하지 않습니다."
+            for pkg in packages:
+                success, err = await _pip_install(pkg, confirmed=True, actor=actor)
+                if not success:
+                    return False, err
+            return _verify_action(action)
+    return False, "자동 복구 방법을 찾지 못했습니다."
+
+
+async def install_stream(
+    items: List[Dict],
+    router: Any,
+    *,
+    confirmation_token: str | None = None,
+    user_email: str | None = None,
+) -> AsyncIterator[str]:
+    for item in items:
+        item_id    = item.get("id", "unknown")
+        name       = item.get("name", item_id)
+        action     = item.get("action") or {}
+        atype      = action.get("type")
+
+        if not atype:
+            yield _sse({"id": item_id, "status": "skipped", "msg": f"{name} — 이미 준비됨"})
+            await asyncio.sleep(0.04)
+            continue
+
+        yield _sse({"id": item_id, "status": "starting", "msg": f"{name} 준비 중..."})
+
+        if atype == "pip":
+            packages = action.get("packages", [])
+            token = confirmation_token or action.get("confirmation_token") or (action.get("command_plan") or {}).get("confirmation_token")
+            if not _verify_action_confirmation(action, token, name=str(item_id)):
+                yield _sse({"id": item_id, "status": "error", "msg": "설치 명령 확인 토큰이 일치하지 않습니다."})
+                continue
+            ok = True
+            for pkg in packages:
+                yield _sse({"id": item_id, "status": "running", "msg": f"pip install {pkg} ..."})
+                success, err = await _pip_install(pkg, confirmed=True, actor=user_email)
+                if success:
+                    yield _sse({"id": item_id, "status": "progress", "msg": f"{pkg} 설치 완료"})
+                else:
+                    yield _sse({"id": item_id, "status": "error", "msg": f"{pkg} 실패: {err[:400]}"})
+                    ok = False
+                    break
+            if ok:
+                yield _sse({"id": item_id, "status": "running", "msg": f"{name} 동작 테스트 중..."})
+                verified, detail = _verify_action(action)
+                if verified:
+                    yield _sse({"id": item_id, "status": "done", "msg": f"{name} 설치 · 검증 완료 ✅\n{detail}"})
+                else:
+                    yield _sse({"id": item_id, "status": "running", "msg": f"검증 실패 — 자동 복구 중...\n{detail}"})
+                    repaired, repair_msg = await _repair_action(action, confirmation_token=token, actor=user_email)
+                    yield _sse({"id": item_id, "status": "done" if repaired else "error", "msg": repair_msg[:500]})
+
+        elif atype == "brew":
+            pkg = action.get("package", "")
+            token = confirmation_token or action.get("confirmation_token") or (action.get("command_plan") or {}).get("confirmation_token")
+            if not _verify_action_confirmation(action, token, name=str(item_id)):
+                yield _sse({"id": item_id, "status": "error", "msg": "설치 명령 확인 토큰이 일치하지 않습니다."})
+                continue
+            yield _sse({"id": item_id, "status": "running", "msg": f"brew install {pkg} ..."})
+            success, err = await _brew_install(pkg, confirmed=True, actor=user_email)
+            if success:
+                yield _sse({"id": item_id, "status": "running", "msg": "설치 완료 감지 · PATH 보정 중..."})
+                binary = action.get("binary")
+                if binary:
+                    repair_path_for(binary)
+                verified, detail = _verify_action(action)
+                if verified:
+                    yield _sse({"id": item_id, "status": "done", "msg": f"{name} 설치 · 연결 · 검증 완료 ✅\n{detail}"})
+                else:
+                    yield _sse({"id": item_id, "status": "running", "msg": f"검증 실패 — 자동 복구 중...\n{detail}"})
+                    repaired, repair_msg = await _repair_action(action, confirmation_token=token, actor=user_email)
+                    yield _sse({"id": item_id, "status": "done" if repaired else "error", "msg": repair_msg[:500]})
+            else:
+                url = action.get("official_url") or action.get("url")
+                if url:
+                    yield _sse({"id": item_id, "status": "auth", "msg": f"자동 설치 실패 — 공식 다운로드 페이지를 엽니다.\n{err[:240]}", "auth_url": url})
+                    open_url(url)
+                yield _sse({"id": item_id, "status": "error", "msg": f"실패: {err[:400]}"})
+
+        elif atype == "load_model":
+            model_id = action.get("model_id", "")
+            yield _sse({"id": item_id, "status": "running",
+                        "msg": f"모델 다운로드 · 로딩 중...\n{model_id}\n(용량에 따라 수 분 소요)"})
+            try:
+                await router.load_model(model_id)
+                yield _sse({"id": item_id, "status": "done", "msg": f"{name} 로드 완료 ✅"})
+            except Exception as e:
+                yield _sse({"id": item_id, "status": "error", "msg": f"로드 실패: {str(e)[:400]}"})
+
+        elif atype == "auth":
+            url = action.get("url", "")
+            yield _sse({"id": item_id, "status": "auth",
+                        "msg": "브라우저에서 인증 페이지를 엽니다...", "auth_url": url})
+            open_url(url)
+            yield _sse({"id": item_id, "status": "waiting",
+                        "msg": "브라우저에서 인증 완료 후 계속하세요"})
+
+        elif atype == "url":
+            url = action.get("url", "")
+            yield _sse({"id": item_id, "status": "auth",
+                        "msg": "설치 페이지를 브라우저에서 엽니다...", "auth_url": url})
+            open_url(url)
+            binary = action.get("binary")
+            if binary:
+                yield _sse({"id": item_id, "status": "waiting",
+                            "msg": f"{binary} 설치 완료를 자동 감지하는 중입니다..."})
+                ok, detail = await _wait_for_binary(binary)
+                if ok:
+                    repair_path_for(binary)
+                    yield _sse({"id": item_id, "status": "done",
+                                "msg": f"{name} 설치 · PATH 연결 · 검증 완료 ✅\n{detail}"})
+                else:
+                    yield _sse({"id": item_id, "status": "error",
+                                "msg": f"{detail}\n공식 페이지에서 설치 후 다시 시도하세요."})
+            else:
+                yield _sse({"id": item_id, "status": "waiting",
+                            "msg": "브라우저에서 설치 또는 인증을 완료한 뒤 다시 시도하세요"})
+
+        else:
+            yield _sse({"id": item_id, "status": "error", "msg": f"알 수 없는 액션: {atype}"})
+
+    yield _sse({"status": "complete", "msg": "모든 항목 처리 완료!"})
+
+
+async def _pip_install(
+    package: str,
+    *,
+    confirmation_token: str | None = None,
+    confirmed: bool = False,
+    actor: str | None = None,
+) -> Tuple[bool, str]:
+    command = [sys.executable, "-m", "pip", "install", "--upgrade", package]
+    plan = command_plan(
+        command,
+        name=f"pip:{package}",
+        purpose="setup_wizard_install",
+        metadata={"package": package},
+    )
+    try:
+        if not confirmed:
+            require_command_confirmation(command, confirmation_token, purpose="setup_wizard_install")
+        append_process_audit_event("setup_wizard_install", plan=plan, status="started", user_email=actor)
+        proc = await asyncio.create_subprocess_exec(
+            *command,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await asyncio.wait_for(proc.communicate(), timeout=600)
+        stderr_text = stderr.decode(errors="replace")
+        append_process_audit_event(
+            "setup_wizard_install",
+            plan=plan,
+            status="finished",
+            user_email=actor,
+            returncode=proc.returncode,
+            stderr=stderr_text,
+        )
+        if proc.returncode == 0:
+            return True, ""
+        return False, stderr_text
+    except CommandConfirmationError as e:
+        append_process_audit_event("setup_wizard_install", plan=plan, status="denied", user_email=actor, error=str(e))
+        return False, str(e)
+    except asyncio.TimeoutError:
+        append_process_audit_event("setup_wizard_install", plan=plan, status="timeout", user_email=actor)
+        return False, "설치 시간 초과 (10분)"
+    except Exception as e:
+        append_process_audit_event("setup_wizard_install", plan=plan, status="error", user_email=actor, error=str(e))
+        return False, str(e)
+
+
+async def _brew_install(
+    package: str,
+    *,
+    confirmation_token: str | None = None,
+    confirmed: bool = False,
+    actor: str | None = None,
+) -> Tuple[bool, str]:
+    brew = shutil.which("brew")
+    if not brew:
+        return False, "Homebrew 미설치 — https://brew.sh 에서 설치하세요"
+    command = [brew, "install", package]
+    plan = command_plan(
+        command,
+        name=f"brew:{package}",
+        purpose="setup_wizard_install",
+        metadata={"package": package},
+    )
+    try:
+        if not confirmed:
+            require_command_confirmation(command, confirmation_token, purpose="setup_wizard_install")
+        append_process_audit_event("setup_wizard_install", plan=plan, status="started", user_email=actor)
+        proc = await asyncio.create_subprocess_exec(
+            *command,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await asyncio.wait_for(proc.communicate(), timeout=300)
+        stderr_text = stderr.decode(errors="replace")
+        append_process_audit_event(
+            "setup_wizard_install",
+            plan=plan,
+            status="finished",
+            user_email=actor,
+            returncode=proc.returncode,
+            stderr=stderr_text,
+        )
+        if proc.returncode == 0:
+            return True, ""
+        return False, stderr_text
+    except CommandConfirmationError as e:
+        append_process_audit_event("setup_wizard_install", plan=plan, status="denied", user_email=actor, error=str(e))
+        return False, str(e)
+    except asyncio.TimeoutError:
+        append_process_audit_event("setup_wizard_install", plan=plan, status="timeout", user_email=actor)
+        return False, "설치 시간 초과 (5분)"
+    except Exception as e:
+        append_process_audit_event("setup_wizard_install", plan=plan, status="error", user_email=actor, error=str(e))
+        return False, str(e)
+
+
+def open_url(url: str) -> None:
+    command: List[str]
+    try:
+        system = platform.system()
+        if system == "Darwin":
+            command = ["open", url]
+            plan = command_plan(command, name="open_url", purpose="setup_wizard_open_url")
+            append_process_audit_event("setup_wizard_open_url", plan=plan, status="started")
+            subprocess.Popen(command)
+            append_process_audit_event("setup_wizard_open_url", plan=plan, status="spawned")
+        elif system == "Windows":
+            command = ["os.startfile", url]
+            plan = command_plan(command, name="open_url", purpose="setup_wizard_open_url")
+            append_process_audit_event("setup_wizard_open_url", plan=plan, status="started")
+            os.startfile(url)  # type: ignore[attr-defined]  # noqa: S606 — fixed program, arguments validated by the caller
+            append_process_audit_event("setup_wizard_open_url", plan=plan, status="spawned")
+        else:
+            command = ["xdg-open", url]
+            plan = command_plan(command, name="open_url", purpose="setup_wizard_open_url")
+            append_process_audit_event("setup_wizard_open_url", plan=plan, status="started")
+            subprocess.Popen(command)
+            append_process_audit_event("setup_wizard_open_url", plan=plan, status="spawned")
+    except Exception as exc:
+        try:
+            append_process_audit_event(
+                "setup_wizard_open_url",
+                plan=command_plan(["open_url", url], name="open_url", purpose="setup_wizard_open_url"),
+                status="error",
+                error=str(exc),
+            )
+        except Exception:
+            quiet()
+        pass

package/latticeai/setup/wizard/paths.py

@@ -0,0 +1,168 @@
+"""PATH discovery, binary lookup, and the ``.env`` handoff for the wizard.
+
+The base layer of the setup wizard: it knows where installers put things on
+each platform, how to get those directories onto ``PATH`` for the running
+process, and how to persist that repair into the project ``.env``. Nothing
+here imports another wizard submodule, which is also what lets
+``tests/unit/test_cov_wp04_wizard_detect.py`` re-execute this file under a
+throwaway name to reach the Windows-only import-time branch.
+
+``COMMON_PATH_DIRS`` is module-level state that the import-time Windows block
+extends and tests replace, so it lives here and only here — the modules that
+repair PATH call :func:`repair_path_for` rather than copying the list.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List
+
+OFFICIAL_DOWNLOADS: Dict[str, str] = {
+    "homebrew": "https://brew.sh",
+    "python": "https://www.python.org/downloads/",
+    "node": "https://nodejs.org/en/download",
+    "git": "https://git-scm.com/downloads",
+    "ollama": "https://ollama.com/download",
+    "lmstudio": "https://lmstudio.ai/download",
+    "cuda": "https://developer.nvidia.com/cuda-downloads",
+    "mlx": "https://ml-explore.github.io/mlx/build/html/install.html",
+    "cloudflared": "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+    "tesseract": "https://tesseract-ocr.github.io/tessdoc/Installation.html",
+}
+
+COMMON_PATH_DIRS = [
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    str(Path.home() / ".local" / "bin"),
+    str(Path.home() / ".cargo" / "bin"),
+    str(Path.home() / ".latticeai" / "bin"),
+]
+
+if platform.system() == "Windows":
+    _local_appdata = os.environ.get("LOCALAPPDATA", "")
+    _program_files = os.environ.get("ProgramFiles", r"C:\Program Files")
+    _program_files_x86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
+    COMMON_PATH_DIRS.extend([
+        str(Path(_local_appdata) / "Programs" / "Ollama") if _local_appdata else "",
+        str(Path(_program_files) / "Ollama"),
+        str(Path(_program_files) / "LM Studio"),
+        str(Path(_program_files) / "NVIDIA Corporation" / "NVSMI"),
+        str(Path(_program_files_x86) / "NVIDIA Corporation" / "NVSMI"),
+    ])
+    COMMON_PATH_DIRS = [p for p in COMMON_PATH_DIRS if p]
+
+WINDOWS_BINARY_CANDIDATES: Dict[str, List[str]] = {
+    "ollama": [
+        str(Path(os.environ.get("LOCALAPPDATA", "")) / "Programs" / "Ollama" / "ollama.exe"),
+        str(Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "Ollama" / "ollama.exe"),
+    ],
+    "lms": [
+        str(Path(os.environ.get("LOCALAPPDATA", "")) / "Programs" / "LM Studio" / "resources" / "app" / ".webpack" / "lms.exe"),
+        str(Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "LM Studio" / "resources" / "app" / ".webpack" / "lms.exe"),
+    ],
+    "nvidia-smi": [
+        str(Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "NVIDIA Corporation" / "NVSMI" / "nvidia-smi.exe"),
+        str(Path(os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")) / "NVIDIA Corporation" / "NVSMI" / "nvidia-smi.exe"),
+    ],
+}
+
+PACKAGE_MODULES: Dict[str, str] = {
+    "mlx-vlm": "mlx_vlm",
+    "huggingface_hub[cli]": "huggingface_hub",
+    "openai-whisper": "whisper",
+}
+
+
+def _project_env_file() -> Path:
+    return Path(__file__).resolve().parents[2] / ".env"
+
+
+def _update_env_file(env_file: Path, key: str, value: str) -> None:
+    lines: List[str] = []
+    found = False
+    if env_file.exists():
+        lines = env_file.read_text(encoding="utf-8").splitlines()
+    updated: List[str] = []
+    for line in lines:
+        if line.startswith(f"{key}="):
+            updated.append(f"{key}={value}")
+            found = True
+        else:
+            updated.append(line)
+    if not found:
+        updated.append(f"{key}={value}")
+    env_file.write_text("\n".join(updated) + "\n", encoding="utf-8")
+
+
+def _merge_path_dirs(dirs: List[str]) -> List[str]:
+    current = os.environ.get("PATH", "")
+    parts = [p for p in current.split(os.pathsep) if p]
+    for item in dirs:
+        expanded = str(Path(item).expanduser())
+        if Path(expanded).exists() and expanded not in parts:
+            parts.insert(0, expanded)
+    os.environ["PATH"] = os.pathsep.join(parts)
+    return parts
+
+
+def _persist_extra_path(dirs: List[str]) -> None:
+    existing = [
+        p for p in os.environ.get("LATTICEAI_EXTRA_PATH", "").split(os.pathsep)
+        if p
+    ]
+    merged = existing[:]
+    for item in dirs:
+        expanded = str(Path(item).expanduser())
+        if Path(expanded).exists() and expanded not in merged:
+            merged.append(expanded)
+    if merged:
+        os.environ["LATTICEAI_EXTRA_PATH"] = os.pathsep.join(merged)
+        _update_env_file(_project_env_file(), "LATTICEAI_EXTRA_PATH", os.environ["LATTICEAI_EXTRA_PATH"])
+
+
+def repair_path_for(binary: str | None = None) -> List[str]:
+    before = _which_any(binary) if binary else None
+    paths = _merge_path_dirs(COMMON_PATH_DIRS)
+    if binary and not before and _which_any(binary):
+        _persist_extra_path(COMMON_PATH_DIRS)
+    return paths
+
+
+def _which_any(binary: str) -> str | None:
+    path = shutil.which(binary)
+    if path:
+        return path
+    if platform.system() == "Windows":
+        for candidate in WINDOWS_BINARY_CANDIDATES.get(binary, []):
+            if candidate and Path(candidate).exists():
+                return candidate
+    return None
+
+
+def _which_detail(binary: str) -> Dict[str, Any]:
+    path = _which_any(binary)
+    return {"installed": path is not None, "path": path}
+
+
+def _module_available(module_name: str) -> bool:
+    import importlib.util
+    return importlib.util.find_spec(module_name) is not None
+
+
+def _package_module(package: str) -> str:
+    return PACKAGE_MODULES.get(package, package.replace("-", "_").split("[", 1)[0])
+
+
+def _component_detail(name: str, binary: str | None = None, module: str | None = None) -> Dict[str, Any]:
+    detail: Dict[str, Any] = {"official_url": OFFICIAL_DOWNLOADS.get(name)}
+    if binary:
+        detail.update(_which_detail(binary))
+    if module:
+        detail["module_available"] = _module_available(module)
+        detail["installed"] = bool(detail.get("installed") or detail["module_available"])
+    return detail

package/latticeai/setup/wizard/plans.py

@@ -0,0 +1,74 @@
+"""SSE framing and the confirmation-token plans for wizard install actions.
+
+Every install action the wizard offers is turned into an explicit command plan
+before it is shown, so the token the browser sends back can be compared against
+the exact commands that would run. An action with nothing to execute has no
+plan and therefore nothing to confirm.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from typing import Any, Dict, List
+
+from latticeai.services.process_audit import command_plan_for_commands
+
+
+def _sse(data: Dict) -> str:
+    return f"data: {_json.dumps(data, ensure_ascii=False)}\n\n"
+
+
+def _action_commands(action: Dict[str, Any]) -> List[List[str]]:
+    atype = action.get("type")
+    if atype == "pip":
+        return [[sys.executable, "-m", "pip", "install", "--upgrade", str(pkg)] for pkg in action.get("packages", [])]
+    if atype == "brew":
+        package = str(action.get("package") or "")
+        return [["brew", "install", package]] if package else []
+    return []
+
+
+def _action_command_plan(action: Dict[str, Any], *, name: str) -> Dict[str, Any] | None:
+    commands = _action_commands(action)
+    if not commands:
+        return None
+    return command_plan_for_commands(
+        commands,
+        name=name,
+        purpose="setup_wizard_install",
+        metadata={"action_type": action.get("type")},
+    )
+
+
+def _attach_action_plan(action: Dict[str, Any] | None, *, name: str) -> Dict[str, Any] | None:
+    if not isinstance(action, dict):
+        return action
+    plan = _action_command_plan(action, name=name)
+    if not plan:
+        return action
+    hydrated = dict(action)
+    hydrated["command_plan"] = plan
+    hydrated["confirmation_token"] = plan["confirmation_token"]
+    return hydrated
+
+
+def _hydrate_install_actions(groups: Dict[str, Any]) -> Dict[str, Any]:
+    for group_name in ("components", "engines", "models", "mcps"):
+        items = groups.get(group_name)
+        if not isinstance(items, list):
+            continue
+        for item in items:
+            if isinstance(item, dict):
+                item["action"] = _attach_action_plan(
+                    item.get("action"),
+                    name=str(item.get("id") or item.get("name") or group_name),
+                )
+    return groups
+
+
+def _verify_action_confirmation(action: Dict[str, Any], token: str | None, *, name: str) -> bool:
+    plan = _action_command_plan(action, name=name)
+    if not plan:
+        return True
+    return str(token or "").strip() == plan["confirmation_token"]