chatup 0.2.15__tar.gz → 0.2.17__tar.gz

{chatup-0.2.15/src/chatup.egg-info → chatup-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatup
-Version: 0.2.15
+Version: 0.2.17
 Summary: ChatArch setup CLI extracted from ChatTool
 Author-email: rexwzh <1073853456@qq.com>
 License-Expression: MIT
@@ -62,6 +62,8 @@ chatup playwright install 1.61.1 -I
 chatup workspace default ~/Playground
 ```
 
+`chatup uv` 默认更新已有 `~/.bashrc`、`~/.zshrc` 的自动激活块；使用 `chatup uv --no-activate` 可保持启动配置不变。不会创建缺失的 rc 文件，Windows 跳过此项。
+
 常见安装命令：
 
 ```bash
@@ -74,16 +76,40 @@ chatup nginx proxy-pass ./gitea-local.conf --set SERVER_NAME=gitea.local.example
 chatup crs --install-dir ~/.chatarch/crs/local --port 12392 --redis-port 6379
 ```
 
+## Chrome 与 iTerm2
+
+```bash
+chatup chrome --dry-run
+chatup chrome             # 按系统安装普通 Google Chrome
+chatup iterm              # 安装 iTerm2，仅限 macOS
+chatup chrome --sudo --yes # Linux：允许提权并确认包安装
+```
+
+macOS 直接下载官方 DMG/ZIP 并校验开发者签名，无需 Homebrew；默认装到 `/Applications`，不可写时使用 `~/Applications`。Windows 使用 WinGet `Google.Chrome`；Linux x86_64 使用官方 DEB/RPM 与 apt/dnf/yum/zypper。已安装时验证并复用，不改默认浏览器、终端或用户配置。自动化浏览器仍使用 `chatup chrome-for-testing`。详见[安装约定](https://arch.gh.wzhecnu.cn/ChatUp/commands/#chrome-iterm)。
+
+## ChatGPT / Codex 桌面应用
+
+```bash
+chatup chatgpt --dry-run
+chatup chatgpt
+chatup chatgpt --yes  # Windows 首次安装时接受 Store 协议
+```
+
+安装包含 Codex 的新版官方 ChatGPT 桌面应用。macOS 需要 Homebrew，Windows 需要 WinGet；Linux preview 暂按[官方说明](https://learn.chatgpt.com/docs/linux/linux-app)手动安装。现有 `chatup codex` 仍安装/配置 Codex CLI。不会自动启动、登录或升级已有应用；[完整约定](https://arch.gh.wzhecnu.cn/ChatUp/commands/#chatgpt-desktop)。
+
+`chatup codex`、`chatup hermes` 未配置模型时默认使用 `gpt-5.6-terra`；用户指定的模型和已有配置仍优先。
+
 ## 当前能力
 
 | 能力组 | 命令 |
 | --- | --- |
 | 基础运行环境 | `doctor`、`uv`、`nodejs`、`docker`、`zsh`、`chrome-for-testing`、`chromedriver`、`playwright`、`frp` |
 | 工作区脚手架 | `workspace` |
+| 桌面应用 | `chrome`、`iterm`（仅 macOS）、`chatgpt`（含 Codex） |
 | 本地服务安装 | `gitea`、`discourse`、`zulip`、`mysql`、`nginx`、`crs` |
 | Agent 工具链 | `cc-connect`、`claude`、`codex`、`cursor-agent`、`opencode`、`hermes`、`lark-cli` |
 
-所有新增安装项默认目录都收敛到 `~/.chatarch/...`，例如 `~/.chatarch/chrome-for-testing`、`~/.chatarch/chromedriver`、`~/.chatarch/playwright`、`~/.chatarch/chattea`、`~/.chatarch/discourse`、`~/.chatarch/zulip`、`~/.chatarch/chatdata`、`~/.chatarch/nginx` 和 `~/.chatarch/crs/local`。`cursor-agent` 额外注册 ChatEnv `CursorAgent` profile，`discourse`/`zulip` 注册管理员凭据 profile，并支持 `-e/--env` 从 env 文件或 profile 快速配置；显式选择 profile 时不会混入进程环境中的其他账号凭据。CLI 树由 ChatStyle 的注册表渲染。更完整的能力边界见 `docs/capability-map.md`。
+桌面应用使用系统原生应用目录；ChatArch 自管安装项默认目录收敛到 `~/.chatarch/...`，例如 `~/.chatarch/chrome-for-testing`、`~/.chatarch/chromedriver`、`~/.chatarch/playwright`、`~/.chatarch/chattea`、`~/.chatarch/discourse`、`~/.chatarch/zulip`、`~/.chatarch/chatdata`、`~/.chatarch/nginx` 和 `~/.chatarch/crs/local`。`cursor-agent` 额外注册 ChatEnv `CursorAgent` profile，`discourse`/`zulip` 注册管理员凭据 profile，并支持 `-e/--env` 从 env 文件或 profile 快速配置；显式选择 profile 时不会混入进程环境中的其他账号凭据。CLI 树由 ChatStyle 的注册表渲染。更完整的能力边界见 `docs/capability-map.md`。
 
 ## 开发
 

{chatup-0.2.15 → chatup-0.2.17}/README.md

@@ -31,6 +31,8 @@ chatup playwright install 1.61.1 -I
 chatup workspace default ~/Playground
 ```
 
+`chatup uv` 默认更新已有 `~/.bashrc`、`~/.zshrc` 的自动激活块；使用 `chatup uv --no-activate` 可保持启动配置不变。不会创建缺失的 rc 文件，Windows 跳过此项。
+
 常见安装命令：
 
 ```bash
@@ -43,16 +45,40 @@ chatup nginx proxy-pass ./gitea-local.conf --set SERVER_NAME=gitea.local.example
 chatup crs --install-dir ~/.chatarch/crs/local --port 12392 --redis-port 6379
 ```
 
+## Chrome 与 iTerm2
+
+```bash
+chatup chrome --dry-run
+chatup chrome             # 按系统安装普通 Google Chrome
+chatup iterm              # 安装 iTerm2，仅限 macOS
+chatup chrome --sudo --yes # Linux：允许提权并确认包安装
+```
+
+macOS 直接下载官方 DMG/ZIP 并校验开发者签名，无需 Homebrew；默认装到 `/Applications`，不可写时使用 `~/Applications`。Windows 使用 WinGet `Google.Chrome`；Linux x86_64 使用官方 DEB/RPM 与 apt/dnf/yum/zypper。已安装时验证并复用，不改默认浏览器、终端或用户配置。自动化浏览器仍使用 `chatup chrome-for-testing`。详见[安装约定](https://arch.gh.wzhecnu.cn/ChatUp/commands/#chrome-iterm)。
+
+## ChatGPT / Codex 桌面应用
+
+```bash
+chatup chatgpt --dry-run
+chatup chatgpt
+chatup chatgpt --yes  # Windows 首次安装时接受 Store 协议
+```
+
+安装包含 Codex 的新版官方 ChatGPT 桌面应用。macOS 需要 Homebrew，Windows 需要 WinGet；Linux preview 暂按[官方说明](https://learn.chatgpt.com/docs/linux/linux-app)手动安装。现有 `chatup codex` 仍安装/配置 Codex CLI。不会自动启动、登录或升级已有应用；[完整约定](https://arch.gh.wzhecnu.cn/ChatUp/commands/#chatgpt-desktop)。
+
+`chatup codex`、`chatup hermes` 未配置模型时默认使用 `gpt-5.6-terra`；用户指定的模型和已有配置仍优先。
+
 ## 当前能力
 
 | 能力组 | 命令 |
 | --- | --- |
 | 基础运行环境 | `doctor`、`uv`、`nodejs`、`docker`、`zsh`、`chrome-for-testing`、`chromedriver`、`playwright`、`frp` |
 | 工作区脚手架 | `workspace` |
+| 桌面应用 | `chrome`、`iterm`（仅 macOS）、`chatgpt`（含 Codex） |
 | 本地服务安装 | `gitea`、`discourse`、`zulip`、`mysql`、`nginx`、`crs` |
 | Agent 工具链 | `cc-connect`、`claude`、`codex`、`cursor-agent`、`opencode`、`hermes`、`lark-cli` |
 
-所有新增安装项默认目录都收敛到 `~/.chatarch/...`，例如 `~/.chatarch/chrome-for-testing`、`~/.chatarch/chromedriver`、`~/.chatarch/playwright`、`~/.chatarch/chattea`、`~/.chatarch/discourse`、`~/.chatarch/zulip`、`~/.chatarch/chatdata`、`~/.chatarch/nginx` 和 `~/.chatarch/crs/local`。`cursor-agent` 额外注册 ChatEnv `CursorAgent` profile，`discourse`/`zulip` 注册管理员凭据 profile，并支持 `-e/--env` 从 env 文件或 profile 快速配置；显式选择 profile 时不会混入进程环境中的其他账号凭据。CLI 树由 ChatStyle 的注册表渲染。更完整的能力边界见 `docs/capability-map.md`。
+桌面应用使用系统原生应用目录；ChatArch 自管安装项默认目录收敛到 `~/.chatarch/...`，例如 `~/.chatarch/chrome-for-testing`、`~/.chatarch/chromedriver`、`~/.chatarch/playwright`、`~/.chatarch/chattea`、`~/.chatarch/discourse`、`~/.chatarch/zulip`、`~/.chatarch/chatdata`、`~/.chatarch/nginx` 和 `~/.chatarch/crs/local`。`cursor-agent` 额外注册 ChatEnv `CursorAgent` profile，`discourse`/`zulip` 注册管理员凭据 profile，并支持 `-e/--env` 从 env 文件或 profile 快速配置；显式选择 profile 时不会混入进程环境中的其他账号凭据。CLI 树由 ChatStyle 的注册表渲染。更完整的能力边界见 `docs/capability-map.md`。
 
 ## 开发
 

{chatup-0.2.15 → chatup-0.2.17}/src/chatup/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.15"
+__version__ = "0.2.17"

{chatup-0.2.15 → chatup-0.2.17}/src/chatup/cli.py

@@ -6,6 +6,7 @@ from chatstyle import add_tree_option
 from chatup import __version__
 from chatup.commands.chrome_for_testing import cli as chrome_for_testing_cli
 from chatup.commands.chromedriver import cli as chromedriver_cli
+from chatup.commands.desktop import chrome_cli, iterm_cli
 from chatup.commands.playwright import cli as playwright_cli
 from chatup.setup.cli import register_setup_commands
 
@@ -32,6 +33,8 @@ register_setup_commands(main)
 main.add_command(chrome_for_testing_cli)
 main.add_command(chromedriver_cli)
 main.add_command(playwright_cli)
+main.add_command(chrome_cli)
+main.add_command(iterm_cli)
 
 
 if __name__ == "__main__":

chatup-0.2.17/src/chatup/commands/desktop.py

@@ -0,0 +1,50 @@
+"""CLI entry points for native desktop app installation."""
+from __future__ import annotations
+
+import shlex
+
+import click
+
+
+def _install(app: str, **kwargs) -> None:
+    from chatup.setup.desktop import setup_desktop_app
+
+    try:
+        result = setup_desktop_app(app, **kwargs)
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if result["status"] == "planned":
+        click.echo(f"{result['app']} install plan ({result['platform']}):")
+        if "url" in result:
+            click.echo(f"Download: {result['url']}")
+        if "path" in result:
+            click.echo(f"Install to: {result['path']} (verify publisher signature)")
+        if "command" in result:
+            click.echo(shlex.join(result["command"]))
+        click.echo("Dry run: no download or installation performed.")
+        return
+    status = "Already installed" if result["status"] == "already_installed" else "Installed"
+    click.echo(f"{status}: {result['app']} {result.get('version', '')}".strip())
+    if "path" in result:
+        click.echo(result["path"])
+    elif "binary" in result:
+        click.echo(result["binary"])
+    click.echo("Installation verified.")
+
+
+@click.command(name="chrome")
+@click.option("--dry-run", is_flag=True, help="Show the installation plan without downloading or installing.")
+@click.option("--sudo", is_flag=True, help="Allow sudo for Linux system package installation.")
+@click.option("--yes", "-y", is_flag=True, help="Accept Windows agreements or Linux package-manager prompts.")
+@click.option("--log-level", type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), default="INFO")
+def chrome_cli(**kwargs) -> None:
+    """Install regular Google Chrome for macOS, Windows or Linux."""
+    _install("chrome", **kwargs)
+
+
+@click.command(name="iterm")
+@click.option("--dry-run", is_flag=True, help="Show the installation plan without downloading or installing.")
+@click.option("--log-level", type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), default="INFO")
+def iterm_cli(**kwargs) -> None:
+    """Install iTerm2 from the official download (macOS only)."""
+    _install("iterm", **kwargs)

chatup-0.2.17/src/chatup/setup/chatgpt.py

@@ -0,0 +1,132 @@
+"""Install the official ChatGPT desktop app (the successor to Codex App).
+
+The OS package manager owns downloads, signatures, application paths and state.
+This module never launches the app or changes Codex CLI configuration/auth.
+"""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from typing import Any
+
+CHATGPT_CASK = "homebrew/cask/chatgpt"
+CHATGPT_STORE_ID = "9PLM9XGG6VKS"
+DOWNLOAD_URL = "https://chatgpt.com/download/"
+LINUX_GUIDE_URL = "https://learn.chatgpt.com/docs/linux/linux-app"
+
+
+def plan_chatgpt_install(*, yes: bool = False) -> dict[str, Any]:
+    """Return a side-effect-free install plan for the current OS.
+
+    ``yes`` explicitly accepts Microsoft Store source/package agreements.
+    Homebrew/WinGet resolve the current release and enforce OS/CPU requirements.
+    Linux preview installation is deliberately not automated here.
+    """
+    system = platform.system()
+    if system == "Darwin":
+        manager = "brew"
+        package = CHATGPT_CASK
+        command = [manager, "install", "--cask", package]
+        verify_command = [manager, "list", "--cask", "--versions", package]
+        manager_url = "https://brew.sh/"
+    elif system == "Windows":
+        manager = "winget"
+        package = CHATGPT_STORE_ID
+        selector = ["--id", package, "--exact", "--source", "msstore", "--disable-interactivity"]
+        command = [manager, "install", *selector, "--no-upgrade"]
+        verify_command = [manager, "list", *selector]
+        if yes:
+            command += ["--accept-package-agreements", "--accept-source-agreements"]
+            verify_command += ["--accept-source-agreements"]
+        manager_url = "https://aka.ms/getwinget"
+    else:
+        guide = LINUX_GUIDE_URL if system == "Linux" else DOWNLOAD_URL
+        raise RuntimeError(
+            f"ChatUp automates ChatGPT desktop installation on macOS and Windows only; "
+            f"current platform: {system}. Official downloads/instructions: {guide}"
+        )
+    return {
+        "app": "ChatGPT (includes Codex)",
+        "platform": system,
+        "manager": manager,
+        "manager_url": manager_url,
+        "package": package,
+        "command": command,
+        "verify_command": verify_command,
+        "download_url": DOWNLOAD_URL,
+    }
+
+
+def _is_installed(plan: dict[str, Any], executable: str) -> bool:
+    result = subprocess.run(
+        [executable, *plan["verify_command"][1:]],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+        timeout=60,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        return False
+    if plan["manager"] == "brew":
+        for line in result.stdout.splitlines():
+            parts = line.split()
+            if len(parts) < 2 or parts[0] != "chatgpt":
+                continue
+            if any(version.startswith("1.") for version in parts[1:]):
+                raise RuntimeError(
+                    "An older ChatGPT Classic cask is registered as chatgpt. "
+                    "Migrate it manually with Homebrew before installing the new "
+                    f"ChatGPT/Codex app: {DOWNLOAD_URL}"
+                )
+            return True
+        return False
+    # WinGet's exact Store selector exits zero only when a matching package exists.
+    return True
+
+
+def setup_chatgpt(*, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    """Install if absent, then verify registration with the package manager.
+
+    Returns the plan plus ``status`` (planned/already_installed/installed) and
+    ``verified``. Dry-run does not require or invoke a package manager. Existing
+    installations are not upgraded, overwritten or migrated; authentication and
+    launching remain user actions. Raises RuntimeError on failed/unknown results.
+    """
+    plan = plan_chatgpt_install(yes=yes)
+    result = {**plan, "status": "planned", "verified": False}
+    if dry_run:
+        return result
+    executable = shutil.which(plan["manager"])
+    if not executable:
+        raise RuntimeError(
+            f"Required package manager {plan['manager']} is not on PATH. "
+            f"Install it first: {plan['manager_url']} or download manually: {DOWNLOAD_URL}"
+        )
+    try:
+        if _is_installed(plan, executable):
+            return {**result, "status": "already_installed", "verified": True}
+        installed = subprocess.run(
+            [executable, *plan["command"][1:]], check=False, timeout=1800,
+        )
+        if installed.returncode != 0:
+            hint = " Use --yes to accept Store agreements." if plan["manager"] == "winget" and not yes else ""
+            raise RuntimeError(
+                f"ChatGPT installer failed (exit {installed.returncode}). "
+                f"Check the package manager output above.{hint}"
+            )
+        if not _is_installed(plan, executable):
+            raise RuntimeError(
+                "ChatGPT installation verification failed. Check the package manager "
+                "state before retrying; installation success is not confirmed."
+            )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(
+            "ChatGPT package manager timed out; the installation state is unknown. "
+            "Check the package manager before retrying."
+        ) from exc
+    except OSError as exc:
+        raise RuntimeError(f"Cannot execute {plan['manager']}: {exc}") from exc
+    return {**result, "status": "installed", "verified": True}

{chatup-0.2.15 → chatup-0.2.17}/src/chatup/setup/codex.py

@@ -30,7 +30,7 @@ from chatup.setup.nodejs import (
 from chatup.utils.custom_logger import setup_logger
 from chatup.utils.platforming import chmod_private
 
-DEFAULT_MODEL = "gpt-5.5"
+DEFAULT_MODEL = "gpt-5.6-terra"
 DEFAULT_BASE_URL = "https://api.openai.com/v1"
 DEFAULT_AUTH_METHOD = "apikey"
 _ENV_VAR_REF_RE = re.compile(r"\$(?:\{[^}]+\}|[A-Za-z_][A-Za-z0-9_]*)")

chatup-0.2.17/src/chatup/setup/desktop.py

@@ -0,0 +1,279 @@
+"""Native installers for regular Google Chrome and the macOS iTerm2 app."""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+import platform
+import plistlib
+import re
+import shutil
+import subprocess
+import tempfile
+from typing import Any
+import urllib.request
+
+from chatup.runtime._managed_artifact import safe_extract_zip
+from chatup.utils.custom_logger import setup_logger
+
+logger = logging.getLogger(__name__)
+
+MAC_APPS = {
+    "chrome": {
+        "app": "Google Chrome",
+        "bundle": "Google Chrome.app",
+        "bundle_id": "com.google.Chrome",
+        "team_id": "EQHXZ8M8AV",
+        "url": "https://dl.google.com/chrome/mac/universal/stable/GGRO/googlechrome.dmg",
+        "format": "dmg",
+    },
+    "iterm": {
+        "app": "iTerm2",
+        "bundle": "iTerm.app",
+        "bundle_id": "com.googlecode.iterm2",
+        "team_id": "H7V7XYVQ7D",
+        "url": "https://iterm2.com/downloads/stable/latest",
+        "format": "zip",
+    },
+}
+LINUX_PACKAGES = {
+    "apt-get": ("deb", ["install"]),
+    "dnf": ("rpm", ["install"]),
+    "yum": ("rpm", ["install"]),
+    "zypper": ("rpm", ["install"]),
+}
+
+
+def _mac_app_dirs() -> tuple[Path, Path]:
+    return Path("/Applications"), Path.home() / "Applications"
+
+
+def _is_root() -> bool:
+    return hasattr(os, "geteuid") and os.geteuid() == 0
+
+
+def plan_desktop_install(
+    app: str, *, sudo: bool = False, yes: bool = False,
+) -> dict[str, Any]:
+    """Describe the current platform's installation without writes or processes."""
+    spec = MAC_APPS[app]
+    system = platform.system()
+    plan = {"app": spec["app"], "platform": system}
+    if app == "iterm" and system != "Darwin":
+        raise RuntimeError(f"iTerm2 is supported on macOS only; current platform: {system}.")
+    if system == "Darwin":
+        if platform.machine().lower() not in {"arm64", "aarch64", "x86_64", "amd64"}:
+            raise RuntimeError(f"Unsupported macOS architecture: {platform.machine()}.")
+        directories = _mac_app_dirs()
+        existing = next((d / spec["bundle"] for d in directories if (d / spec["bundle"]).exists()), None)
+        directory = directories[0] if os.access(directories[0], os.W_OK) else directories[1]
+        return {**plan, **spec, "method": "macos", "path": str(existing or directory / spec["bundle"])}
+    if system == "Windows":
+        selector = ["--id", "Google.Chrome", "--exact", "--source", "winget", "--disable-interactivity"]
+        command = ["winget", "install", *selector, "--silent", "--no-upgrade"]
+        verify = ["winget", "list", *selector]
+        if yes:
+            command += ["--accept-package-agreements", "--accept-source-agreements"]
+            verify += ["--accept-source-agreements"]
+        return {**plan, "method": "winget", "command": command, "verify_command": verify}
+    if system == "Linux":
+        if platform.machine().lower() not in {"x86_64", "amd64"}:
+            raise RuntimeError("Google Chrome for Linux requires x86_64; Google does not provide a Linux ARM package.")
+        manager = next((name for name in LINUX_PACKAGES if shutil.which(name)), None)
+        if not manager:
+            raise RuntimeError("Google Chrome requires apt-get, dnf, yum or zypper on Linux. See https://www.google.com/chrome/.")
+        extension, action = LINUX_PACKAGES[manager]
+        filename = f"google-chrome-stable_current_{'amd64' if extension == 'deb' else 'x86_64'}.{extension}"
+        command = [manager]
+        if manager == "zypper" and yes:
+            command += ["--non-interactive"]
+        command += action
+        if manager != "zypper" and yes:
+            command += ["-y"]
+        command += ["{package}"]
+        if sudo and not _is_root():
+            command.insert(0, "sudo")
+        return {**plan, "method": "linux", "manager": manager, "command": command,
+                "url": f"https://dl.google.com/linux/direct/{filename}", "filename": filename}
+    raise RuntimeError(f"Google Chrome installation is not supported on {system}.")
+
+
+def _run(command: list[str], *, capture: bool = True, timeout: int = 1800, check: bool = True):
+    logger.debug("Running: %s", command)
+    result = subprocess.run(
+        command, capture_output=capture, text=True, encoding="utf-8", errors="replace",
+        timeout=timeout, check=False,
+    )
+    if check and result.returncode:
+        detail = (result.stderr or result.stdout or "See installer output.").strip()
+        raise RuntimeError(f"{Path(command[0]).name} failed (exit {result.returncode}): {detail[-2000:]}")
+    return result
+
+
+def _download(url: str, destination: Path) -> None:
+    logger.info("Downloading %s", url)
+    request = urllib.request.Request(url, headers={"User-Agent": "ChatUp desktop installer"})
+    with urllib.request.urlopen(request, timeout=120) as response, destination.open("wb") as output:
+        if not response.url.startswith("https://"):
+            raise RuntimeError("Refusing a download redirected away from HTTPS.")
+        total = 0
+        expected = int(response.headers.get("Content-Length", "0"))
+        limit = 1024 * 1024 * 1024
+        if expected > limit:
+            raise RuntimeError("Desktop installer exceeds the 1 GiB download limit.")
+        for chunk in iter(lambda: response.read(1024 * 1024), b""):
+            total += len(chunk)
+            if total > limit:
+                raise RuntimeError("Desktop installer exceeds the 1 GiB download limit.")
+            output.write(chunk)
+        if not total or (expected and total != expected):
+            raise RuntimeError("Desktop installer download is incomplete; retry the command.")
+
+
+def _cache_dir() -> Path:
+    home = Path(os.environ.get("CHATARCH_HOME", str(Path.home() / ".chatarch"))).expanduser()
+    cache = home / "cache" / "desktop"
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache
+
+
+def _mac_bundle(plan: dict[str, Any], path: Path) -> dict[str, str]:
+    try:
+        with (path / "Contents" / "Info.plist").open("rb") as stream:
+            info = plistlib.load(stream)
+        executable_name = info.get("CFBundleExecutable", "")
+        binary = path / "Contents" / "MacOS" / executable_name
+        version = info.get("CFBundleShortVersionString", "")
+        if (info.get("CFBundleIdentifier") != plan["bundle_id"] or not version
+                or not executable_name or Path(executable_name).name != executable_name
+                or not binary.is_file() or not os.access(binary, os.X_OK)):
+            raise ValueError("bundle identity, version or executable is invalid")
+        minimum = info.get("LSMinimumSystemVersion", "")
+        current = platform.mac_ver()[0]
+        if minimum and current:
+            def version_tuple(value):
+                return tuple(int(part) for part in value.split(".")) + (0,) * (3 - len(value.split(".")))
+            if version_tuple(current) < version_tuple(minimum):
+                raise ValueError(f"requires macOS {minimum} or later; current: {current}")
+    except (OSError, ValueError, plistlib.InvalidFileException) as exc:
+        raise RuntimeError(f"Cannot verify {plan['app']} at {path}: {exc}. Existing apps are never overwritten.") from exc
+    requirement = f'=anchor apple generic and certificate leaf[subject.OU] = "{plan["team_id"]}"'
+    _run(["/usr/bin/codesign", "--verify", "--deep", "--strict", "-R", requirement, str(path)], timeout=120)
+    return {"path": str(path), "binary": str(binary), "version": str(version)}
+
+
+def _install_macos(plan: dict[str, Any]) -> dict[str, Any]:
+    target = Path(plan["path"])
+    if target.exists() or target.is_symlink():
+        logger.info("Checking existing %s", target)
+        return {**plan, **_mac_bundle(plan, target), "status": "already_installed", "verified": True}
+    work = Path(tempfile.mkdtemp(prefix="install-", dir=_cache_dir()))
+    mount = work / "volume"
+    mounted = False
+    try:
+        archive = work / f"download.{plan['format']}"
+        _download(plan["url"], archive)
+        if plan["format"] == "dmg":
+            mount.mkdir()
+            _run(["/usr/bin/hdiutil", "attach", str(archive), "-mountpoint", str(mount),
+                  "-nobrowse", "-readonly", "-noautoopen"], timeout=120)
+            mounted = True
+            source = mount / plan["bundle"]
+        else:
+            source = work / "unpacked" / plan["bundle"]
+            safe_extract_zip(archive, source.parent, label=plan["app"])
+        logger.info("Verifying %s publisher signature and app bundle", plan["app"])
+        _mac_bundle(plan, source)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        # Stage on the target filesystem so the final app appears in one rename.
+        with tempfile.TemporaryDirectory(prefix=".chatup-", dir=target.parent) as staging:
+            staged = Path(staging) / plan["bundle"]
+            logger.info("Installing %s", target)
+            _run(["/usr/bin/ditto", str(source), str(staged)])
+            _mac_bundle(plan, staged)
+            if target.exists() or target.is_symlink():
+                raise RuntimeError(f"App appeared during installation; refusing to overwrite {target}.")
+            staged.rename(target)
+        details = _mac_bundle(plan, target)
+        return {**plan, **details, "status": "installed", "verified": True}
+    finally:
+        if mounted:
+            detached = _run(["/usr/bin/hdiutil", "detach", str(mount)], timeout=120, check=False)
+            if detached.returncode:
+                _run(["/usr/bin/hdiutil", "detach", "-force", str(mount)], timeout=120, check=False)
+        # Never recursively clean up a still-mounted disk image.
+        if not os.path.ismount(mount):
+            shutil.rmtree(work)
+        else:
+            logger.warning("Disk image still mounted at %s; installer cache retained at %s", mount, work)
+
+
+def _linux_chrome() -> dict[str, str] | None:
+    binary = shutil.which("google-chrome-stable") or shutil.which("google-chrome")
+    if not binary:
+        return None
+    result = _run([binary, "--version"], timeout=30, check=False)
+    match = re.match(r"Google Chrome (\d+(?:\.\d+)+)", result.stdout.strip())
+    if result.returncode or not match:
+        raise RuntimeError(f"Cannot verify regular Google Chrome at {binary}.")
+    return {"binary": binary, "version": match.group(1)}
+
+
+def _install_linux(plan: dict[str, Any], *, sudo: bool) -> dict[str, Any]:
+    existing = _linux_chrome()
+    if existing:
+        return {**plan, **existing, "status": "already_installed", "verified": True}
+    if not _is_root() and not sudo:
+        raise RuntimeError("Installing Google Chrome on Linux requires root. Re-run: chatup chrome --sudo (optionally --yes).")
+    if not _is_root() and not shutil.which("sudo"):
+        raise RuntimeError("sudo is unavailable; run chatup chrome as root.")
+    with tempfile.TemporaryDirectory(prefix="chrome-", dir=_cache_dir()) as staging:
+        package = Path(staging) / plan["filename"]
+        _download(plan["url"], package)
+        command = [str(package) if arg == "{package}" else arg for arg in plan["command"]]
+        logger.info("Installing Google Chrome with %s", plan["manager"])
+        _run(command, capture=False)
+    installed = _linux_chrome()
+    if not installed:
+        raise RuntimeError("Google Chrome installation verification failed: browser executable not found.")
+    return {**plan, **installed, "status": "installed", "verified": True}
+
+
+def _install_windows(plan: dict[str, Any]) -> dict[str, Any]:
+    executable = shutil.which("winget")
+    if not executable:
+        raise RuntimeError("WinGet is required to install Google Chrome: https://aka.ms/getwinget")
+
+    def installed():
+        result = _run([executable, *plan["verify_command"][1:]], timeout=120, check=False)
+        return result.returncode == 0 and re.search(r"\bGoogle\.Chrome\b", result.stdout) is not None
+
+    if installed():
+        return {**plan, "status": "already_installed", "verified": True}
+    logger.info("Installing Google Chrome with WinGet; use --yes to accept source/package agreements")
+    _run([executable, *plan["command"][1:]], capture=False)
+    if not installed():
+        raise RuntimeError("Google Chrome installation verification failed: no matching WinGet package record.")
+    return {**plan, "status": "installed", "verified": True}
+
+
+def setup_desktop_app(
+    app: str, *, dry_run: bool = False, sudo: bool = False, yes: bool = False,
+    log_level: str = "INFO",
+) -> dict[str, Any]:
+    """Install a native app if absent and verify it; never launch or upgrade it."""
+    global logger
+    logger = setup_logger(__name__, log_level=log_level)
+    try:
+        plan = plan_desktop_install(app, sudo=sudo, yes=yes)
+        if dry_run:
+            return {**plan, "status": "planned", "verified": False}
+        logger.info("Checking %s installation on %s", plan["app"], plan["platform"])
+        if plan["method"] == "macos":
+            return _install_macos(plan)
+        if plan["method"] == "linux":
+            return _install_linux(plan, sudo=sudo)
+        return _install_windows(plan)
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as exc:
+        logger.error("%s installation failed: %s", MAC_APPS[app]["app"], exc)
+        raise RuntimeError(f"{MAC_APPS[app]['app']} installation failed: {exc}") from exc