pkgmate 0.0.1__py3-none-any.whl

pkgtool/base.py

@@ -0,0 +1,238 @@
+"""pkgtool.base — 跨格式统一数据模型、后端契约、文件扫描。
+
+这一层只定义"数据长什么样"，不含任何展示文案（见 labels.py）和采集逻辑
+（见 backends/）。核心设计约束：
+
+  · 结论一律用枚举 code 存，不存中文显示串。原实现把结论编码进
+    origin="local(不在任何源)" / channel="preinstalled(镜像自带)" 这类字符串，
+    三个调用方各自用 startswith 反解，字面量一改就静默出错。
+  · 「安装通道」(channel) 与「当前是否在 apt 源里」(in_repo) 是两个正交维度，
+    必须分开存。原实现挤在 extra["channel"] 一个字段里，导致后端算出的
+    preinstalled 结论被上层用索引结论覆盖（154 个镜像自带包被误报成 apt 安装）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .config import CFG
+
+# 包名 / 版本 / flatpak app-id 的白名单。允许 epoch 的冒号、Debian 版本的 ~ +，
+# 以及下划线——flatpak 的 app-id 规范允许 [A-Za-z0-9._-]，实际大量存在
+# （app.zen_browser.zen），漏掉下划线会导致这些应用根本装不了。
+_SAFE_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9.:+_\-~]{0,199}$")
+
+
+def is_safe_name(value):
+    """校验将被拼进 apt/snap/flatpak 命令行的标识符。
+    首字符必须字母数字：拒绝前导 '-'（会被当成选项，属参数注入）、
+    空白与 shell 元字符。所有写操作入口都必须先过这一关。"""
+    return bool(value) and bool(_SAFE_NAME_RE.match(str(value)))
+
+
+BYTES_PER_MB = 1048576
+
+# 搜索时当成词分隔符的字符：空白 + app.zen_browser.zen 里的 . 和 _
+_QUERY_SPLIT_RE = re.compile(r"[\s._\-/+:]+")
+
+
+def query_tokens(q):
+    """把查询串拆成小写 token：空白与 . _ - / + : 都算分隔符。
+    整串子串匹配搜不到 "zen browser"→app.zen_browser.zen（一边是空格、
+    一边是下划线），拆词后两边归一到同一形态才能对上。"""
+    return [t for t in _QUERY_SPLIT_RE.split((q or "").lower()) if t]
+
+
+def matches_tokens(haystack, tokens):
+    """全部 token 都出现才算命中（AND 语义）。haystack 同样先做分隔符归一。"""
+    if not tokens:
+        return False
+    h = " " + _QUERY_SPLIT_RE.sub(" ", (haystack or "").lower()) + " "
+    return all(t in h for t in tokens)
+
+
+def file_size_mb(path):
+    """文件/目录占用（MB，一位小数）。目录递归累加，读不到的条目跳过。"""
+    total = 0
+    try:
+        if os.path.isfile(path) or os.path.islink(path):
+            total = os.path.getsize(path)
+        else:
+            for dirpath, _dirs, files in os.walk(path):
+                for f in files:
+                    try:
+                        total += os.path.getsize(os.path.join(dirpath, f))
+                    except OSError:
+                        continue
+    except OSError:
+        return 0.0
+    return round(total / BYTES_PER_MB, 1)
+
+
+def is_under_home(path, cfg=CFG):
+    """路径是否在当前用户主目录内（决定删除要不要特权）。"""
+    home = os.path.abspath(cfg.home) + os.sep
+    return os.path.abspath(path).startswith(home)
+
+
+def delete_paths(paths):
+    """普通用户权限删除文件/目录 → (成功列表, 失败信息列表)。"""
+    removed, failed = [], []
+    for p in paths:
+        try:
+            if os.path.isdir(p) and not os.path.islink(p):
+                shutil.rmtree(p)
+            else:
+                os.unlink(p)
+            removed.append(p)
+        except OSError as e:
+            failed.append(f"{p}: {e}")
+    return removed, failed
+
+
+class Channel(str, Enum):
+    """安装通道：这个包是怎么进到系统里的。"""
+    APT = "apt"                    # 仓库安装，apt 可管理
+    APT_LOCAL = "apt-local"        # apt install ./x.deb：历史有记录但当前无源可更新
+    DPKG_LOCAL = "dpkg-local"      # dpkg -i 手动安装
+    PREINSTALLED = "preinstalled"  # 镜像自带（出生时间窗内装入）
+    UNKNOWN = "unknown"            # dpkg.log 与 apt history 都查无记录
+
+
+class OriginKind(str, Enum):
+    """来源：包从哪来。"""
+    REPO = "repo"                  # (包, 版本) 精确命中某个已配置源
+    REPO_STALE = "repo-stale"      # 包在源里但版本对不上：源已更新或源被移除
+    LOCAL = "local"                # 不在任何源 = 本地 .deb
+    FILE = "file"                  # 磁盘上散落的包文件（未安装 / 已安装的重复文件）
+
+
+class PkgClass(str, Enum):
+    """卸载风险分类：只有 APP 允许删（判定规则见 classify.py）。"""
+    BASE = "base"
+    LIBRARY = "library"
+    SYSTEM = "system"
+    APP = "app"
+    FILE = "file"
+
+
+def _code(v):
+    return v.value if isinstance(v, Enum) else (v or "")
+
+
+@dataclass
+class PackageRecord:
+    """一条已安装包的记录（跨格式统一结构）。"""
+    pkg_type: str
+    name: str
+    version: str = "?"
+    variant: str = ""            # 同名多实例的区分维度（flatpak 的 arch/branch）
+    origin_kind: OriginKind = OriginKind.LOCAL
+    origin_repos: list = field(default_factory=list)
+    channel: Channel | None = None
+    pkg_class: PkgClass | None = None
+    class_reason: str = ""
+    in_repo: bool = False
+    candidate: str = ""
+    size_mb: float = 0.0         # 包自身已安装体积
+    exclusive_deps: list = field(default_factory=list)   # 只被它一个包依赖的包
+    deps_size_mb: float = 0.0    # 上面那些独占依赖的体积合计
+    install_path: str = ""
+    executables: list = field(default_factory=list)
+    first_install: str = ""
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def key(self):
+        """全局唯一键：(类型, 名称, 变体)。用于按名字定位记录与去重。"""
+        return (self.pkg_type, self.name, self.variant)
+
+    @property
+    def upgradable(self):
+        return bool(self.candidate)
+
+    @property
+    def is_loose_file(self):
+        """磁盘上的包文件（不是一条已安装记录）。"""
+        return bool(self.extra.get("loose"))
+
+    @property
+    def total_size_mb(self):
+        """自身 + 独占依赖。独占依赖 = 只有这个包在用、没人共用的那些，
+        删掉这个包它们也就没用了（定义见 apt/deps.py）。"""
+        return round(self.size_mb + self.deps_size_mb, 1)
+
+    def to_row(self):
+        """→ CSV 行。全部用 code，extra 用 JSON（原先 k=v 空格拼接会被含空格的值破坏）。"""
+        return [self.pkg_type, self.name, self.variant, self.version,
+                _code(self.origin_kind), ";".join(self.origin_repos),
+                _code(self.channel), int(self.in_repo), self.candidate,
+                _code(self.pkg_class), self.class_reason,
+                self.size_mb, len(self.exclusive_deps), self.deps_size_mb,
+                self.total_size_mb, self.install_path,
+                ";".join(self.executables), self.first_install,
+                json.dumps(self.extra, ensure_ascii=False, sort_keys=True)]
+
+
+CSV_HEADER = ["pkg_type", "name", "variant", "version", "origin_kind",
+              "origin_repos", "channel", "in_repo", "candidate", "pkg_class",
+              "class_reason", "size_mb", "exclusive_deps", "deps_size_mb",
+              "total_size_mb", "install_path", "executables", "first_install",
+              "extra"]
+
+
+class Backend(ABC):
+    """一种包格式的后端。新增格式 = 新建 backends/<fmt>.py + 在 backends/__init__ 注册。
+
+    契约：只采集事实，不做分类判定（pkg_class 留给 inventory 层统一填，
+    避免原实现里 deb 在后端分类、snap/flatpak 在 UI 分类的不对称）。
+    """
+    pkg_type: str = "?"
+
+    def __init__(self, cfg=CFG):
+        self.cfg = cfg
+
+    @classmethod
+    @abstractmethod
+    def available(cls, cfg=CFG) -> bool:
+        """该包管理体系在这台机器上是否存在（不得抛异常）。"""
+
+    @abstractmethod
+    def collect(self) -> list:
+        """返回 [PackageRecord, ...]。实现要求：
+        - 优先读文件系统/缓存目录（离线可用、无需 root）
+        - CLI 查询仅作增强，失败要能降级
+        """
+
+
+def scan_file_areas(suffixes, maxdepth=None, cfg=CFG):
+    """扫描用户可写区域里的包文件（.deb/.AppImage…），不进隐藏目录/缓存。
+    覆盖：主目录（含中文"下载"）+ config.scan_system_roots。realpath 去重。"""
+    maxdepth = cfg.scan_maxdepth if maxdepth is None else maxdepth
+    suf = tuple(s.lower() for s in suffixes)
+    seen = set()
+    for root in cfg.scan_roots:
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            depth = dirpath[len(root):].count(os.sep)
+            dirnames[:] = [d for d in dirnames
+                           if d not in cfg.prune_dirs and not d.startswith(".")]
+            if depth >= maxdepth:
+                dirnames[:] = []
+            for f in filenames:
+                if not f.lower().endswith(suf):
+                    continue
+                p = os.path.join(dirpath, f)
+                try:
+                    rp = os.path.realpath(p)
+                except OSError:
+                    continue
+                if rp not in seen:
+                    seen.add(rp)
+                    yield p

pkgtool/catalog.py

@@ -0,0 +1,345 @@
+"""pkgtool.catalog — 跨格式远程目录搜索与安装（apt / snap / flatpak）。
+
+三个来源的取数方式差别很大，这里统一成 CatalogItem：
+
+  apt      读本地 /var/lib/apt/lists 索引。离线、毫秒级、含描述与全部候选版本。
+  snap     `snap find`，联网查 Snap Store，约 2 秒，含发布者/注记/摘要。
+  flatpak  `flatpak remote-ls`，读本地 remote 的 refs 缓存，0.3 秒 / 3483 条，
+           能拿到安装体积，但**没有描述**——描述在 appstream 目录缓存里。
+
+flatpak 为什么不用 `flatpak search`：它依赖 remote 的 appstream 缓存，本机
+没有时会去联网拉取，实测挂住 25 秒且无任何输出。remote-ls 走 refs 缓存，
+稳定可用，代价是搜不到摘要、只能按名字和 app-id 匹配。
+
+各源结果都缓存：flatpak 缓存全量清单（之后每次搜索只是本地过滤，输入即搜），
+snap 按查询词缓存（它必须联网，不能每敲一个字符就打一次商店）。
+"""
+import os
+import re
+import shutil
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+
+from .apt import actions, lists
+from .base import is_safe_name, matches_tokens, query_tokens
+from .config import CFG
+
+SOURCES = ("apt", "snap", "flatpak")
+
+_SNAP_SPLIT_RE = re.compile(r"\s{2,}")
+_FLATPAK_COLUMNS = "name,application,installed,branch"
+_C_ENV = {"LC_ALL": "C", "LANG": "C"}      # 固定表头语言，解析才稳
+
+_LOCK = threading.Lock()
+_FLATPAK_CACHE = {"t": 0.0, "items": None}
+_SNAP_CACHE = {}
+
+# 最近一次 search() 的每源耗时与失败信息，供界面提示"哪个源慢/挂了"
+LAST_ELAPSED = {}
+LAST_ERRORS = []
+
+
+@dataclass(slots=True)
+class CatalogItem:
+    """一条可安装条目（跨源统一结构）。"""
+    source: str                 # apt / snap / flatpak
+    name: str                   # 安装标识：apt 包名 / snap 名 / flatpak app-id
+    display: str = ""           # 显示名（flatpak 有独立的 name 字段）
+    version: str = ""
+    summary: str = ""
+    publisher: str = ""         # apt 维护者 / snap 发布者 / flatpak remote
+    size_text: str = ""
+    channel: str = ""           # apt 的 suite/component、snap 的注记、flatpak 的 branch
+    remote: str = ""            # flatpak 的 remote 名
+    classic: bool = False       # snap 经典 confinement，安装时必须带 --classic
+    installed: bool = False     # 本机是否已装
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def title(self):
+        return self.display or self.name
+
+
+def _run(argv, cfg, timeout=None):
+    """跑一个查询命令 → (stdout 行列表, 失败原因)。
+    任何失败都转成空结果 + 错误串（搜索不该抛异常），调用方借此区分
+    "确实没搜到"和"查询失败"——snapd 忙碌时 snap find 会失败，静默吞掉
+    会让用户把"查询挂了"当成"商店里没有"。"""
+    try:
+        p = subprocess.run(argv, capture_output=True, text=True,
+                           timeout=timeout or cfg.timeout_catalog,
+                           env=dict(os.environ, **_C_ENV))
+    except (OSError, subprocess.SubprocessError) as e:
+        return [], f"{type(e).__name__}: {e}"
+    if p.returncode != 0:
+        tail = [ln for ln in (p.stderr or "").splitlines() if ln.strip()]
+        return [], tail[-1][:200] if tail else f"退出码 {p.returncode}"
+    return p.stdout.splitlines(), ""
+
+
+# ---------- 各来源 ----------
+
+
+def _search_apt(q, limit, cfg):
+    out = []
+    for x in lists.load_index(cfg).search(q, limit):
+        out.append(CatalogItem(
+            source="apt", name=x["name"], display=x["name"], version=x["version"],
+            summary=x.get("desc") or "", publisher=x.get("maintainer") or "",
+            size_text=f"{x['size_kb']}K" if x.get("size_kb") else "",
+            channel=" ".join(y for y in (x.get("suite"), x.get("component")) if y),
+            remote=x.get("repo") or "",
+            extra={"section": x.get("section", "")}))
+    return out
+
+
+def _search_snap(q, limit, cfg):
+    """`snap find` 按 2+ 空格分列：Name Version Publisher Notes Summary。
+    表头随 locale 变，所以统一用 LC_ALL=C 固定成英文再跳过首行。"""
+    now = time.time()
+    with _LOCK:
+        hit = _SNAP_CACHE.get(q)
+        if hit and now - hit[0] < cfg.catalog_cache_ttl:
+            return hit[1][:limit]
+    lines, err = _run(["snap", "find", q], cfg)
+    if not lines and err:
+        LAST_ERRORS.append(f"snap: {err}")       # 查询失败要让人看见
+    out = []
+    for i, line in enumerate(lines):
+        f = _SNAP_SPLIT_RE.split(line.strip())
+        if len(f) < 5:
+            continue
+        if i == 0 and f[0] == "Name":
+            continue                                  # 表头
+        notes = f[3]
+        out.append(CatalogItem(source="snap", name=f[0], display=f[0],
+                               version=f[1], publisher=f[2], channel=notes,
+                               summary=" ".join(f[4:]),
+                               classic="classic" in notes.lower()))
+    with _LOCK:
+        _SNAP_CACHE[q] = (now, out)
+    return out[:limit]
+
+
+def flatpak_remote_urls(cfg=CFG, user=False):
+    """→ {remote 名: url}。user=True 查用户级安装。
+    系统级配的 remote 对 --user 安装不可见，这两套是各自独立的配置。"""
+    scope = "--user" if user else "--system"
+    out = {}
+    lines, _err = _run(["flatpak", "remotes", scope, "--columns=name,url"], cfg)
+    for line in lines:
+        f = line.split("\t")
+        if len(f) >= 2 and f[0].strip():
+            out[f[0].strip()] = f[1].strip()
+    return out
+
+
+def flatpak_remotes(cfg=CFG):
+    return list(flatpak_remote_urls(cfg))
+
+
+def flatpak_user_missing_remote(remote, cfg=CFG):
+    """--user 安装前检查该 remote 在用户级是否存在；缺失时返回可直接执行的修复命令。
+    系统级与用户级是两套独立的 remote 配置，只配了系统级时 --user 会报
+    "未发现用于 xxx 的远程引用"，那句报错看不出该怎么修。"""
+    if remote in flatpak_remote_urls(cfg, user=True):
+        return ""
+    head = f"用户级 flatpak 安装里没有 “{remote}”（系统级配的 remote 对 --user 不可见）。"
+    url = flatpak_remote_urls(cfg).get(remote, "")
+    if not url:
+        return head + f" 系统级也没配，无法推断 URL，请手动 flatpak remote-add --user {remote} <url>"
+    # ostree 约定：<repo 根>/<remote 名>.flatpakrepo，不把 flathub 地址写死在代码里
+    ref = url.rstrip("/") + f"/{remote}.flatpakrepo"
+    return f"{head}\n    先执行：flatpak remote-add --user {remote} {ref}"
+
+
+def _flatpak_catalog(cfg):
+    """全部 remote 的应用清单（缓存）。→ [CatalogItem]
+
+    必须逐个 installation 显式指定 --system / --user：同一个 remote 名
+    （flathub）常常两个 installation 都配了，这时不带作用域的
+    `flatpak remote-ls flathub` 会直接报 "Remote 'flathub' found in
+    multiple installations" 并返回空，整个 flatpak 搜索就静默失效了。
+    两个作用域都扫，按 app-id 去重（系统级优先，因为它是默认安装目标）。"""
+    now = time.time()
+    with _LOCK:
+        if _FLATPAK_CACHE["items"] is not None \
+                and now - _FLATPAK_CACHE["t"] < cfg.catalog_cache_ttl:
+            return _FLATPAK_CACHE["items"]
+    out, seen = [], set()
+    for scope, is_user in (("--system", False), ("--user", True)):
+        for remote in flatpak_remote_urls(cfg, user=is_user):
+            lines, _err = _run(["flatpak", "remote-ls", "--app", scope,
+                                f"--columns={_FLATPAK_COLUMNS}", remote], cfg)
+            for line in lines:
+                f = line.split("\t")
+                if len(f) < 4 or not f[1] or f[1] in seen:
+                    continue
+                seen.add(f[1])
+                # flatpak 的体积列用不间断空格分隔（"518.3\xa0MB"），不换成
+                # 普通空格会打乱终端对齐、也没法当普通字符串比较
+                out.append(CatalogItem(source="flatpak", name=f[1], display=f[0],
+                                       size_text=f[2].replace("\xa0", " ").strip(),
+                                       channel=f[3].strip(), publisher=remote,
+                                       remote=remote,
+                                       extra={"scope": "user" if is_user else "system"}))
+    with _LOCK:
+        _FLATPAK_CACHE.update(t=now, items=out)
+    return out
+
+
+def _rank(items, q, limit):
+    """本地过滤 + 排名：完全匹配 > 前缀 > 子串 > 分词全命中。
+    最后一级用分词，这样 "zen browser" 才搜得到 app.zen_browser.zen ——
+    整串子串匹配对不上（名字里是下划线，查询里是空格）。"""
+    ql = q.lower()
+    tokens = query_tokens(q)
+    hits = []
+    for it in items:
+        n, d = it.name.lower(), it.display.lower()
+        if ql in (n, d):
+            r = 0
+        elif n.startswith(ql) or d.startswith(ql):
+            r = 1
+        elif ql in n or ql in d:
+            r = 2
+        elif matches_tokens(f"{it.name} {it.display}", tokens):
+            r = 3
+        else:
+            continue
+        hits.append((r, it.display or it.name, it))
+    hits.sort(key=lambda t: (t[0], t[1]))
+    return [t[2] for t in hits[:limit]]
+
+
+def _search_flatpak(q, limit, cfg):
+    return _rank(_flatpak_catalog(cfg), q, limit)
+
+
+_SEARCHERS = {"apt": _search_apt, "snap": _search_snap, "flatpak": _search_flatpak}
+# 搜索来源名 → PackageRecord.pkg_type（apt 对应的是 deb）
+_SOURCE_TYPE = {"apt": "deb", "snap": "snap", "flatpak": "flatpak"}
+
+
+def available(cfg=CFG):
+    """本机可用的搜索来源。"""
+    out = []
+    if os.path.isdir(cfg.apt_lists_dir):
+        out.append("apt")
+    if shutil.which("snap") and os.path.isdir(cfg.snap_store_dir):
+        out.append("snap")
+    if shutil.which("flatpak"):
+        out.append("flatpak")
+    return tuple(out)
+
+
+def search(query, sources=None, limit=30, cfg=CFG, installed=None):
+    """跨源搜索 → [CatalogItem]，按来源分组、组内按相关度排。
+    sources=None 表示本机全部可用来源；每个来源各自取 limit 条，
+    免得一个源的结果把其他源挤掉。
+    installed 是 {(source, name)} 集合，用来标注"已安装"。"""
+    q = (query or "").strip()
+    if not q:
+        return []
+    sources = tuple(s for s in (sources or available(cfg)) if s in _SEARCHERS)
+    installed = installed or set()
+    out = []
+    LAST_ERRORS.clear()
+    LAST_ELAPSED.clear()
+    for s in sources:
+        pkg_type = _SOURCE_TYPE[s]
+        t0 = time.time()
+        try:
+            found = _SEARCHERS[s](q, limit, cfg)
+        except Exception as e:                        # noqa: BLE001 单源失败不拖垮整体
+            found = []
+            LAST_ERRORS.append(f"{s}: {type(e).__name__}: {e}")
+        LAST_ELAPSED[s] = round(time.time() - t0, 1)
+        for it in found:
+            it.installed = (pkg_type, it.name) in installed
+        out.extend(found)
+    return out
+
+
+def installed_keys(inv):
+    """从 Inventory 提取 {(pkg_type, name)}，供 search 标注已安装。"""
+    return {(r.pkg_type, r.name) for r in inv.records}
+
+
+def installed_names(cfg=CFG, sources=SOURCES):
+    """→ {(pkg_type, name)}，只跑相关的后端，不做全量盘点。
+    搜索不该为了标注"已安装"而等一次 4 秒的全量采集：deb 读 status 只要
+    0.01 秒，snap / flatpak 各自也就 0.1 秒。"""
+    out = set()
+    if "apt" in sources:
+        from .apt import dpkg
+        out |= {("deb", n) for n in dpkg.installed(cfg)}
+    if "snap" in sources:
+        from .backends.snap import SnapBackend
+        if SnapBackend.available(cfg):
+            out |= {("snap", r.name) for r in SnapBackend(cfg).collect()}
+    if "flatpak" in sources:
+        from .backends.flatpak import FlatpakBackend
+        if FlatpakBackend.available(cfg):
+            out |= {("flatpak", r.name) for r in FlatpakBackend(cfg).collect()}
+    return out
+
+
+# ---------- 安装 ----------
+
+
+def install_argv(item, version="", user=False):
+    """→ (argv, privileged)；名称非法时返回 (None, 错误信息)。
+    user=True 只对 flatpak 有意义：装到 ~/.local/share/flatpak，不需要 root。"""
+    if not is_safe_name(item.name):
+        return None, f"名称非法，拒绝安装：{item.name!r}"
+    if item.source == "apt":
+        spec = f"{item.name}={version}" if version else item.name
+        if version and not is_safe_name(version):
+            return None, f"版本非法：{version!r}"
+        return ["apt-get", "install", "-y", spec], True
+    if item.source == "snap":
+        argv = ["snap", "install"]
+        if item.classic:
+            argv.append("--classic")   # 经典 confinement 不带这个标志会直接失败
+        return argv + [item.name], True
+    if item.source == "flatpak":
+        # 作用域必须显式给：remote 同名存在于两个 installation 时，
+        # 不带 --system/--user 的 flatpak 命令会报 multiple installations
+        argv = ["flatpak", "install", "-y", "--user" if user else "--system"]
+        if item.remote and is_safe_name(item.remote):
+            argv.append(item.remote)
+        return argv + [item.name], not user
+    return None, f"不支持安装的来源：{item.source}"
+
+
+def install(item, version="", user=False, on_line=None, cfg=CFG):
+    """安装一条目录项 → actions.Result。"""
+    argv, privileged = install_argv(item, version, user)
+    if argv is None:
+        return actions.Result(ok=False, error=privileged)   # 此时第二项是错误信息
+    if item.source == "flatpak" and user and item.remote:
+        missing = flatpak_user_missing_remote(item.remote, cfg)
+        if missing:
+            return actions.Result(ok=False, error=missing, command=argv)
+    if privileged:
+        return actions.run_privileged(argv, timeout=cfg.timeout_upgrade,
+                                      on_line=on_line, cfg=cfg)
+    return actions.run_plain(argv, timeout=cfg.timeout_upgrade, cfg=cfg)
+
+
+def describe(item, cfg=CFG):
+    """单条详情文本。apt 给全部候选版本，snap 给 `snap info`，flatpak 给基本字段。"""
+    if item.source == "apt":
+        from . import report
+        info = lists.load_index(cfg).info(item.name)
+        return report.render_versions(info) if info else "仓库中无此包"
+    if item.source == "snap":
+        lines, _err = _run(["snap", "info", item.name], cfg)
+        return "\n".join(lines) if lines else "（snap info 无输出）"
+    bits = [("app-id", item.name), ("显示名", item.display),
+            ("remote", item.remote), ("branch", item.channel),
+            ("体积", item.size_text)]
+    return "\n".join(f"  {k:<10}{v}" for k, v in bits if v)