@sakanano-moe/agenthelm 6.5.1 → 6.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakanano-moe/agenthelm",
-  "version": "6.5.1",
+  "version": "6.5.3",
   "description": "agenthelm 命令行：在 Claude Code、Codex、Cursor 间安装、检查与更新 agenthelm 项目管理插件。",
   "license": "MIT",
   "bin": {

package/runtime/agent_pack_config.py

@@ -485,6 +485,34 @@ def _client_plugin_roots(client: str, home: Path) -> list[Path]:
     return []
 
 
+def _version_tuple(value: str) -> tuple[int, ...]:
+    numbers = re.findall(r"\d+", value.split("+", 1)[0])
+    return tuple(int(number) for number in numbers)
+
+
+def _client_marketplace_plugins(client: str, home: Path) -> list[Path]:
+    """Plugin roots the client installed from marketplaces (not agent-pack bootstrap copies)."""
+    found: list[Path] = []
+    if client == "claude":
+        try:
+            records = _read_json(home / ".claude" / "plugins" / "installed_plugins.json").get("plugins", {})
+        except AgentPackError:
+            records = {}
+        for entries in records.values() if isinstance(records, dict) else ():
+            for entry in entries if isinstance(entries, list) else ():
+                path = Path(str(entry.get("installPath", "")))
+                if (path / "plugin.json").is_file():
+                    found.append(path)
+    elif client == "codex":
+        cache = home / ".codex" / "plugins" / "cache"
+        if cache.is_dir() and not cache.is_symlink():
+            for plugin_dir in sorted(path for market in cache.iterdir() if market.is_dir() for path in market.iterdir()):
+                versions = [path for path in plugin_dir.iterdir() if (path / "plugin.json").is_file()] if plugin_dir.is_dir() else []
+                if versions:
+                    found.append(max(versions, key=lambda path: (_version_tuple(path.name), path.name)))
+    return found
+
+
 def _claude_plugin_records(home: Path) -> Path:
     """Install records for Claude Code: one symlink per plugin to its source root."""
     return home / ".claude" / "agent-pack" / "plugins"
@@ -527,6 +555,8 @@ def inventory_client(client: str, home: Path | None = None) -> Inventory:
         for child in sorted(plugin_parent.iterdir(), key=lambda item: item.name):
             if child.is_dir() and (child / "plugin.json").is_file():
                 _merge_inventory(inventory, _inventory_plugin(child, inventory.source))
+    for child in _client_marketplace_plugins(client, home):
+        _merge_inventory(inventory, _inventory_plugin(child, inventory.source))
     known = {Path(item.path).resolve() for item in inventory.skills}
     for skill_root in _client_skill_roots(client, home):
         if not skill_root.is_dir() or skill_root.is_symlink():

package/runtime/agenthelm.py

@@ -37,7 +37,8 @@ DEFAULT_LATEST_URLS = (
 ENV_LATEST = "AGENTHELM_LATEST_URL"
 ENV_DISABLE = "AGENTHELM_NO_UPDATE_CHECK"
 CACHE_TTL_SECONDS = 24 * 3600
-FETCH_TIMEOUT_SECONDS = 3
+# Interactive commands wait longer: some networks reach the site slowly.
+FETCH_TIMEOUT_SECONDS = 10
 HOOK_FETCH_TIMEOUT_SECONDS = 2
 FAILURE_BACKOFF_SECONDS = 6 * 3600
 CONTENT_LOCK = Path(".agents/moe.sakanano.agent-pack/content.lock.json")
@@ -133,10 +134,14 @@ def update_check_enabled(env: Env) -> bool:
 
 # ---------------------------------------------------------------- cloud source
 
-def _fetch(url: str, timeout: float = FETCH_TIMEOUT_SECONDS) -> dict:
+def _fetch_json(url: str, timeout: float = FETCH_TIMEOUT_SECONDS) -> Any:
     request = urllib.request.Request(url, headers={"User-Agent": "agenthelm-check"})
     with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310
-        data = json.loads(response.read().decode("utf-8"))
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _fetch(url: str, timeout: float = FETCH_TIMEOUT_SECONDS) -> dict:
+    data = _fetch_json(url, timeout)
     if not isinstance(data, dict) or data.get("marketplace") != MARKETPLACE:
         raise CheckError(f"{url} is not an agenthelm latest.json")
     return data
@@ -250,7 +255,9 @@ def plugin_findings(latest: dict, installed: list[dict]) -> list[dict]:
     for item in installed:
         target = latest.get("plugins", {}).get(item["plugin"], {}).get("version")
         current = item.get("version") or ""
-        if target is None:
+        if item["client"] == "legacy":
+            status = "legacy"  # a pre-marketplace copy: it gets migrated, not updated
+        elif target is None:
             status = "unknown"
         elif is_newer(target, current):
             status = "behind"
@@ -331,7 +338,8 @@ def opinion_findings(project: Path, installed: list[dict]) -> list[dict]:
     except (OSError, ValueError, KeyError, TypeError) as exc:
         return [{"status": "error", "error": f"{OPINION_LOCK} 无法解析：{exc}"}]
     with tempfile.TemporaryDirectory() as temporary:
-        profile_file = Path(temporary) / "profile.json"
+        # macOS temporary paths live under /var, a symlink opinion-manager refuses.
+        profile_file = Path(temporary).resolve() / "profile.json"
         profile_file.write_text(json.dumps(profile, ensure_ascii=False), encoding="utf-8")
         completed = subprocess.run(
             [sys.executable, str(manager / "runtime" / "opinion_manager.py"), "updates",
@@ -415,7 +423,11 @@ def render_text(report: dict) -> str:
     if not report["plugins"]:
         lines.append("未发现已安装的 agenthelm 插件。")
     for item in report["plugins"]:
-        label = {"behind": "可更新", "current": "最新", "ahead": "高于云端", "unknown": "版本未知"}[item["status"]]
+        label = {"behind": "可更新", "current": "最新", "ahead": "高于云端", "unknown": "版本未知",
+                 "legacy": "旧方式安装，待迁移"}[item["status"]]
+        if item["status"] == "legacy":
+            lines.append(f"  [旧方式] {item['plugin']} {item.get('version')}  {label}")
+            continue
         line = f"  [{item['client']}] {item['plugin']} {item.get('version')} → {item.get('latest')}  {label}"
         if item["status"] == "behind":
             kinds = {"code": "代码", "content": "仅模板/样例", "both": "代码与模板"}
@@ -430,8 +442,6 @@ def render_text(report: dict) -> str:
             hint = UPDATE_HINTS.get(item["client"])
             if hint:
                 line += f"\n      更新：{hint.format(plugin=item['plugin'])}"
-        elif item["client"] == "legacy":
-            line += f"\n      旧方式安装：{UPDATE_HINTS['legacy']}"
         lines.append(line)
     for item in report["content"]:
         if item.get("pack") is None:
@@ -452,6 +462,8 @@ def render_text(report: dict) -> str:
     if not report["plugins"]:
         lines.append(f"运行 `{CLI} install` 预览安装。")
     else:
+        if any(item["status"] == "legacy" for item in report["plugins"]):
+            lines.append(f"旧方式安装可用 `{UPDATE_HINTS['legacy']}` 预览迁移。")
         lines.append(one_line(report) or "全部为最新。")
     return "\n".join(lines) + "\n"
 
@@ -506,9 +518,9 @@ def github_slug(latest: dict) -> str:
 
 def detect_clients(env: Env) -> list[str]:
     found = []
-    if shutil.which("claude") or env.claude_dir.is_dir():
+    if find_cli(env, "claude") or env.claude_dir.is_dir():
         found.append("claude")
-    if shutil.which("codex") or env.codex_dir.is_dir():
+    if find_cli(env, "codex") or env.codex_dir.is_dir():
         found.append("codex")
     if (env.home / ".cursor").is_dir():
         found.append("cursor")
@@ -523,7 +535,29 @@ def _safe_extract(archive: Path, destination: Path) -> None:
                 raise CheckError(f"发布包含越界路径：{member.name}")
             if not (member.isfile() or member.isdir()):
                 raise CheckError(f"发布包含不支持的条目：{member.name}")
-        bundle.extractall(destination)  # noqa: S202 - every member was validated above
+        try:
+            bundle.extractall(destination, filter="data")  # noqa: S202 - members validated above
+        except TypeError:  # Python without extraction filters
+            bundle.extractall(destination)  # noqa: S202
+
+
+def _plugin_versions(latest: dict) -> dict:
+    return {name: item.get("version") for name, item in latest.get("plugins", {}).items()}
+
+
+def github_release(latest: dict) -> dict:
+    """Release details straight from GitHub, used when latest.json came from the raw fallback.
+
+    Accepted only when that tag ships exactly the plugin versions ``latest`` lists,
+    the same rule the site applies before attaching a release.
+    """
+    try:
+        slug = github_slug(latest)
+        release = _fetch_json(f"https://github.com/{slug}/releases/latest/download/release.json")
+        tagged = _fetch_json(f"https://raw.githubusercontent.com/{slug}/{release['tag']}/latest.json")
+    except (OSError, ValueError, KeyError, TypeError, CheckError, urllib.error.URLError):
+        return {}
+    return release if _plugin_versions(tagged) == _plugin_versions(latest) else {}
 
 
 def release_source(latest: dict, workdir: Path, source: Path | None = None) -> Path:
@@ -533,7 +567,7 @@ def release_source(latest: dict, workdir: Path, source: Path | None = None) -> P
         if not (root / "plugins").is_dir():
             raise CheckError(f"{root} 不含 plugins/ 目录")
         return root
-    release = latest.get("release") or {}
+    release = latest.get("release") or github_release(latest)
     tag, digest = release.get("tag"), release.get("tarball_sha256")
     if not tag or not digest:
         raise CheckError("云端 latest.json 没有发布 tag 与摘要；请用 --source 指定本地仓库")
@@ -580,8 +614,34 @@ class Step:
         return data
 
 
-def _need(binary: str) -> str | None:
-    return None if shutil.which(binary) else f"未找到 {binary} 命令"
+def known_cli_locations(env: Env, name: str) -> list[Path]:
+    """Where a client's command line lives when it is not on PATH (GUI apps, per-user installs)."""
+    home = env.home
+    if name == "codex":
+        bundle = "ChatGPT.app/Contents/Resources/codex-cli/bin/codex"
+        return [Path("/Applications") / bundle, home / "Applications" / bundle,
+                home / ".local/bin/codex", Path("/opt/homebrew/bin/codex"), Path("/usr/local/bin/codex")]
+    return [home / ".local/bin" / name, Path("/opt/homebrew/bin") / name, Path("/usr/local/bin") / name]
+
+
+def find_cli(env: Env, name: str) -> str | None:
+    """A client's command line: ``AGENTHELM_<NAME>`` override, then PATH, then the usual app locations."""
+    override = env.get(f"AGENTHELM_{name.upper()}")
+    if override and os.access(override, os.X_OK):
+        return override
+    on_path = shutil.which(name, path=env.get("PATH") or "")
+    if on_path:
+        return on_path
+    for candidate in known_cli_locations(env, name):
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return None
+
+
+def _cli(env: Env, name: str, *args: str) -> tuple[list[str], str | None]:
+    """The command (using the resolved executable) and why it cannot run, if it cannot."""
+    found = find_cli(env, name)
+    return [found or name, *args], (None if found else f"未找到 {name} 命令（已查 PATH 与常见安装位置；可用 AGENTHELM_{name.upper()} 指定）")
 
 
 def install_steps(env: Env, latest: dict, clients: list[str], plugins: list[str], source: Path | None,
@@ -590,17 +650,17 @@ def install_steps(env: Env, latest: dict, clients: list[str], plugins: list[str]
     steps: list[Step] = []
     for client in clients:
         if client == "claude":
-            steps.append(Step("install", "claude", f"Claude Code 添加 agenthelm 市场（{slug}）",
-                              ["claude", "plugin", "marketplace", "add", slug], blocked=_need("claude")))
+            command, blocked = _cli(env, "claude", "plugin", "marketplace", "add", slug)
+            steps.append(Step("install", "claude", f"Claude Code 添加 agenthelm 市场（{slug}）", command, blocked=blocked))
             for plugin in plugins:
-                steps.append(Step("install", "claude", f"Claude Code 安装 {plugin}",
-                                  ["claude", "plugin", "install", f"{plugin}@{MARKETPLACE}"], blocked=_need("claude")))
+                command, blocked = _cli(env, "claude", "plugin", "install", f"{plugin}@{MARKETPLACE}")
+                steps.append(Step("install", "claude", f"Claude Code 安装 {plugin}", command, blocked=blocked))
         elif client == "codex":
-            steps.append(Step("install", "codex", f"Codex 添加 agenthelm 市场（{slug}）",
-                              ["codex", "plugin", "marketplace", "add", slug], blocked=_need("codex")))
+            command, blocked = _cli(env, "codex", "plugin", "marketplace", "add", slug)
+            steps.append(Step("install", "codex", f"Codex 添加 agenthelm 市场（{slug}）", command, blocked=blocked))
             for plugin in plugins:
-                steps.append(Step("install", "codex", f"Codex 安装 {plugin}",
-                                  ["codex", "plugin", "add", f"{plugin}@{MARKETPLACE}"], blocked=_need("codex")))
+                command, blocked = _cli(env, "codex", "plugin", "add", f"{plugin}@{MARKETPLACE}")
+                steps.append(Step("install", "codex", f"Codex 安装 {plugin}", command, blocked=blocked))
         elif client == "cursor":
             steps.append(cursor_step(latest, plugins, source, home, "安装"))
     return steps
@@ -627,17 +687,16 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
     if only in (None, "plugins"):
         claude = sorted({item["plugin"] for item in behind if item["client"] == "claude"})
         if claude:
-            steps.append(Step("update", "claude", "刷新 Claude Code 的 agenthelm 市场",
-                              ["claude", "plugin", "marketplace", "update", MARKETPLACE], blocked=_need("claude")))
+            command, blocked = _cli(env, "claude", "plugin", "marketplace", "update", MARKETPLACE)
+            steps.append(Step("update", "claude", "刷新 Claude Code 的 agenthelm 市场", command, blocked=blocked))
             for item in [entry for entry in behind if entry["client"] == "claude"]:
-                command = ["claude", "plugin", "update", f"{item['plugin']}@{MARKETPLACE}"]
-                if item.get("scope") and item["scope"] != "user":
-                    command += ["--scope", item["scope"]]
+                extra = ["--scope", item["scope"]] if item.get("scope") and item["scope"] != "user" else []
+                command, blocked = _cli(env, "claude", "plugin", "update", f"{item['plugin']}@{MARKETPLACE}", *extra)
                 steps.append(Step("update", "claude", f"Claude Code 更新 {item['plugin']} → {item['latest']}",
-                                  command, blocked=_need("claude")))
+                                  command, blocked=blocked))
         if any(item["client"] == "codex" for item in behind):
-            steps.append(Step("update", "codex", "Codex 升级 agenthelm 市场与已装插件",
-                              ["codex", "plugin", "marketplace", "upgrade", MARKETPLACE], blocked=_need("codex")))
+            command, blocked = _cli(env, "codex", "plugin", "marketplace", "upgrade", MARKETPLACE)
+            steps.append(Step("update", "codex", "Codex 升级 agenthelm 市场与已装插件", command, blocked=blocked))
         cursor = sorted({item["plugin"] for item in behind if item["client"] == "cursor"})
         if cursor:
             steps.append(cursor_step(latest, cursor, source, home, "更新"))
@@ -771,6 +830,10 @@ def legacy_artifacts(env: Env, names: set[str]) -> list[dict]:
                           "path": str(env.home / ".agents/plugins/marketplace.json")})
     for name in _codex_personal_sections(env, names):
         artifacts.append({"kind": "codex-config-section", "name": name, "path": str(env.codex_dir / "config.toml")})
+    for name in sorted(names):
+        cache = env.codex_dir / "plugins" / "cache" / "personal" / name
+        if cache.is_dir() and not cache.is_symlink():
+            artifacts.append({"kind": "codex-personal-cache", "name": name, "path": str(cache)})
     try:
         servers = read_json(env.home / ".claude.json").get("mcpServers", {})
     except (OSError, ValueError, AttributeError):
@@ -799,10 +862,17 @@ def retire_legacy(env: Env, artifacts: list[dict], recovery: Path) -> list[dict]
     done: list[dict] = []
     backed_up: set[str] = set()
 
+    def inside_recovery(path: Path) -> Path:
+        """The path below the recovery folder: home-relative, or absolute for locations outside home."""
+        try:
+            return path.relative_to(env.home)
+        except ValueError:
+            return Path("external") / str(path).lstrip("/")
+
     def backup(path: Path) -> None:
         if str(path) in backed_up:
             return
-        target = recovery / "files" / path.relative_to(env.home)
+        target = recovery / "files" / inside_recovery(path)
         target.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(path, target)
         backed_up.add(str(path))
@@ -812,8 +882,8 @@ def retire_legacy(env: Env, artifacts: list[dict], recovery: Path) -> list[dict]
         if item.get("manual"):
             done.append({**item, "status": "manual"})
             continue
-        if item["kind"] in {"plugin-copy", "plugin-record", "claude-skill-link"}:
-            target = recovery / "moved" / path.relative_to(env.home)
+        if item["kind"] in {"plugin-copy", "plugin-record", "claude-skill-link", "codex-personal-cache"}:
+            target = recovery / "moved" / inside_recovery(path)
             target.parent.mkdir(parents=True, exist_ok=True)
             os.replace(path, target)
             done.append({**item, "status": "moved", "to": str(target)})
@@ -845,9 +915,15 @@ def recovery_dir_for(env: Env, label: str) -> Path:
     return env.home / ".agent-pack" / "recovery" / f"{stamp}-agenthelm-{label}"
 
 
-def locate(env: Env, plugin: str, version: str | None = None) -> dict:
-    """Where a plugin is installed, newest first: the stable lookup for downstream wrappers."""
-    found = [item for item in installed_plugins(env, {plugin}) if version is None or item.get("version") == version]
+def locate(env: Env, plugin: str, version: str | None = None, *, include_legacy: bool = False) -> dict:
+    """Where a plugin is installed, newest first: the stable lookup for downstream wrappers.
+
+    Legacy copies are left out unless asked for, so a wrapper that works today
+    keeps working after ``migrate`` retires them.
+    """
+    found = [item for item in installed_plugins(env, {plugin})
+             if (version is None or item.get("version") == version)
+             and (include_legacy or item["client"] != "legacy")]
     found.sort(key=lambda item: (version_key(item.get("version") or "") or (0,), item["client"] != "legacy"),
                reverse=True)
     return {"ok": bool(found), "plugin": plugin, "version": version,
@@ -930,6 +1006,8 @@ def parser() -> argparse.ArgumentParser:
     locate_parser = sub.add_parser("locate", help="输出插件的已安装位置（最新优先），供下游脚本查找")
     locate_parser.add_argument("plugin")
     locate_parser.add_argument("--version", help="只要这个版本")
+    locate_parser.add_argument("--include-legacy", action="store_true",
+                               help="也列出旧方式安装（默认不列，避免清理后才失效）")
     locate_parser.add_argument("--output", choices=("text", "json"), default="json")
     locate_parser.add_argument("--home", type=Path, help=argparse.SUPPRESS)
     return result
@@ -966,7 +1044,7 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "check" and args.hook:
         return hook(env, project, args.hook_format)
     if args.command == "locate":
-        found = locate(env, args.plugin, args.version)
+        found = locate(env, args.plugin, args.version, include_legacy=args.include_legacy)
         if args.output == "json":
             print(json.dumps(found, ensure_ascii=False, indent=2))
         elif found["path"]: