Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

hermes_cli/plugin_index.py

@@ -0,0 +1,305 @@
+"""Community plugin index — fetch, cache, search, and name resolution.
+
+Mirrors the Skills Hub catalog pattern (``tools/skills_hub.py``): a static
+machine-readable JSON index hosted at a canonical URL, cached locally under
+``HERMES_HOME/cache/`` with a TTL, with a bundled seed file as the offline
+fallback and format reference.
+
+Fallback chain: remote index → cached copy (fresh or stale) → bundled seed.
+
+The index is discovery metadata ONLY.  **Indexed ≠ audited** — inclusion in
+the index means the entry's metadata was reviewed, not that the plugin's code
+was audited.  Install keeps its existing consent/review flow, and index
+entries pin an immutable ref (tag or commit SHA).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, List, Optional
+
+from hermes_constants import get_hermes_home
+
+logger = logging.getLogger(__name__)
+
+# Canonical index location. Override via config key ``plugins.index_url``.
+DEFAULT_INDEX_URL = (
+    "https://raw.githubusercontent.com/NousResearch/hermes-plugin-index/main/index.json"
+)
+
+# Cache the fetched index for 24 hours; a stale cache is still preferred over
+# the bundled seed when the remote is unreachable.
+INDEX_CACHE_TTL = 24 * 3600
+
+# Bundled seed — offline fallback and the machine-readable format reference.
+SEED_INDEX_PATH = Path(__file__).parent / "data" / "plugin_index.json"
+
+_FETCH_TIMEOUT = 10.0
+_MAX_INDEX_BYTES = 5 * 1024 * 1024  # refuse absurdly large index payloads
+
+SECURITY_FOOTER = (
+    "Indexed \u2260 audited: inclusion in the index is a metadata review only, "
+    "not a code audit. Review a plugin before enabling it."
+)
+
+
+@dataclass
+class PluginIndexEntry:
+    """One community plugin index entry."""
+
+    name: str
+    description: str = ""
+    author: str = ""
+    tags: List[str] = field(default_factory=list)
+    repo: str = ""                      # "owner/name"
+    ref: str = ""                       # pinned tag or commit SHA
+    subdir: Optional[str] = None        # path within the repo (monorepos)
+    homepage: Optional[str] = None
+    capabilities: List[str] = field(default_factory=list)
+    api_version: Optional[int] = None
+    added_at: Optional[str] = None
+
+    @property
+    def install_identifier(self) -> str:
+        """Identifier accepted by the existing install path (owner/repo[/subdir])."""
+        return f"{self.repo}/{self.subdir}" if self.subdir else self.repo
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+            "author": self.author,
+            "tags": list(self.tags),
+            "repo": self.repo,
+            "ref": self.ref,
+        }
+        if self.subdir:
+            d["subdir"] = self.subdir
+        if self.homepage:
+            d["homepage"] = self.homepage
+        if self.capabilities:
+            d["capabilities"] = list(self.capabilities)
+        if self.api_version is not None:
+            d["api_version"] = self.api_version
+        if self.added_at:
+            d["added_at"] = self.added_at
+        return d
+
+
+def _cache_path() -> Path:
+    return get_hermes_home() / "cache" / "plugin_index.json"
+
+
+def get_index_url() -> str:
+    """Resolve the index URL: config override ``plugins.index_url`` or default."""
+    try:
+        from hermes_cli.config import cfg_get, load_config_readonly
+
+        override = cfg_get(load_config_readonly(), "plugins", "index_url", default=None)
+        if isinstance(override, str) and override.strip():
+            return override.strip()
+    except Exception:  # pragma: no cover - config loading must never break search
+        logger.debug("plugin index: config override lookup failed", exc_info=True)
+    return DEFAULT_INDEX_URL
+
+
+def _parse_entries(raw: Any) -> List[PluginIndexEntry]:
+    """Parse a decoded index document into entries, skipping malformed items."""
+    if isinstance(raw, dict):
+        items = raw.get("plugins", [])
+    elif isinstance(raw, list):  # bare-list form also accepted
+        items = raw
+    else:
+        raise ValueError("Plugin index must be a JSON object or list.")
+    if not isinstance(items, list):
+        raise ValueError("Plugin index 'plugins' field must be a list.")
+
+    entries: List[PluginIndexEntry] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name")
+        repo = item.get("repo")
+        if not isinstance(name, str) or not name.strip():
+            continue
+        if not isinstance(repo, str) or repo.count("/") != 1 or not all(repo.split("/")):
+            logger.debug("plugin index: skipping entry %r with invalid repo %r", name, repo)
+            continue
+        subdir = item.get("subdir")
+        api_version = item.get("api_version")
+        entries.append(
+            PluginIndexEntry(
+                name=name.strip(),
+                description=str(item.get("description") or ""),
+                author=str(item.get("author") or ""),
+                tags=[str(t) for t in item.get("tags") or [] if isinstance(t, (str, int))],
+                repo=repo.strip(),
+                ref=str(item.get("ref") or ""),
+                subdir=str(subdir).strip("/") if isinstance(subdir, str) and subdir.strip("/") else None,
+                homepage=str(item["homepage"]) if item.get("homepage") else None,
+                capabilities=[str(c) for c in item.get("capabilities") or []],
+                api_version=int(api_version) if isinstance(api_version, (int, str)) and str(api_version).isdigit() else None,
+                added_at=str(item["added_at"]) if item.get("added_at") else None,
+            )
+        )
+    return entries
+
+
+def _load_seed_entries() -> List[PluginIndexEntry]:
+    try:
+        return _parse_entries(json.loads(SEED_INDEX_PATH.read_text(encoding="utf-8")))
+    except (OSError, ValueError) as exc:  # pragma: no cover - bundled file
+        logger.warning("plugin index: bundled seed unreadable: %s", exc)
+        return []
+
+
+def _read_cache(*, max_age: Optional[float]) -> Optional[List[PluginIndexEntry]]:
+    """Return cached entries if the cache exists (and is younger than *max_age*)."""
+    cache = _cache_path()
+    try:
+        if not cache.is_file():
+            return None
+        if max_age is not None:
+            age = time.time() - cache.stat().st_mtime
+            if age > max_age:
+                return None
+        return _parse_entries(json.loads(cache.read_text(encoding="utf-8")))
+    except (OSError, ValueError) as exc:
+        logger.debug("plugin index: cache read failed: %s", exc)
+        return None
+
+
+def _write_cache(text: str) -> None:
+    try:
+        cache = _cache_path()
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        from utils import atomic_write_text
+
+        atomic_write_text(cache, text)
+    except OSError as exc:  # pragma: no cover - best effort
+        logger.debug("plugin index: cache write failed: %s", exc)
+
+
+def _fetch_remote() -> Optional[List[PluginIndexEntry]]:
+    """Fetch and parse the remote index; cache the raw payload on success."""
+    url = get_index_url()
+    try:
+        import httpx
+
+        resp = httpx.get(url, timeout=_FETCH_TIMEOUT, follow_redirects=True)
+        resp.raise_for_status()
+        text = resp.text
+        if len(text.encode("utf-8", errors="ignore")) > _MAX_INDEX_BYTES:
+            raise ValueError("Plugin index payload exceeds size limit.")
+        entries = _parse_entries(json.loads(text))
+        _write_cache(text)
+        return entries
+    except Exception as exc:
+        logger.debug("plugin index: remote fetch failed (%s): %s", url, exc)
+        return None
+
+
+def load_index(*, refresh: bool = False, offline: bool = False) -> tuple[List[PluginIndexEntry], str]:
+    """Load the plugin index.
+
+    Returns ``(entries, source)`` where *source* is one of ``"remote"``,
+    ``"cache"``, or ``"seed"``.
+
+    Order: fresh cache (unless *refresh*) → remote → stale cache → bundled seed.
+    ``offline=True`` skips the network entirely.
+    """
+    if not refresh:
+        cached = _read_cache(max_age=INDEX_CACHE_TTL)
+        if cached is not None:
+            return cached, "cache"
+
+    if not offline:
+        remote = _fetch_remote()
+        if remote is not None:
+            return remote, "remote"
+
+    stale = _read_cache(max_age=None)
+    if stale is not None:
+        return stale, "cache"
+
+    return _load_seed_entries(), "seed"
+
+
+# ---------------------------------------------------------------------------
+# Search
+# ---------------------------------------------------------------------------
+
+def _score_entry(entry: PluginIndexEntry, term: str) -> float:
+    """Fuzzy relevance score for *entry* against lowercase *term* (0 = no match)."""
+    import difflib
+
+    name = entry.name.lower()
+    desc = entry.description.lower()
+    tags = [t.lower() for t in entry.tags]
+
+    if term == name:
+        return 100.0
+    score = 0.0
+    if term in name:
+        score = max(score, 80.0)
+    if any(term == t for t in tags):
+        score = max(score, 70.0)
+    if any(term in t for t in tags):
+        score = max(score, 55.0)
+    if term in desc:
+        score = max(score, 50.0)
+    if term in entry.author.lower():
+        score = max(score, 40.0)
+    # Fuzzy close-match on the name for typo tolerance.
+    ratio = difflib.SequenceMatcher(None, term, name).ratio()
+    if ratio >= 0.6:
+        score = max(score, ratio * 60.0)
+    return score
+
+
+def search_index(
+    entries: List[PluginIndexEntry], term: str, *, capability: Optional[str] = None
+) -> List[PluginIndexEntry]:
+    """Rank *entries* against *term* (fuzzy on name/description/tags/author).
+
+    An empty *term* matches everything (browse mode). ``capability`` filters
+    entries by declared capability.
+    """
+    pool = entries
+    if capability:
+        cap = capability.lower()
+        pool = [e for e in pool if any(cap == c.lower() for c in e.capabilities)]
+
+    term = (term or "").strip().lower()
+    if not term:
+        return sorted(pool, key=lambda e: e.name)
+
+    scored = [(e, _score_entry(e, term)) for e in pool]
+    matched = [(e, s) for e, s in scored if s > 0]
+    matched.sort(key=lambda pair: (-pair[1], pair[0].name))
+    return [e for e, _s in matched]
+
+
+def resolve_name(
+    entries: List[PluginIndexEntry], name: str
+) -> tuple[Optional[PluginIndexEntry], List[PluginIndexEntry]]:
+    """Resolve a bare plugin *name* against the index.
+
+    Returns ``(entry, candidates)``: an exact (case-insensitive) unique match
+    in ``entry``, otherwise ``entry is None`` and ``candidates`` holds any
+    partial matches (empty = nothing similar, >1 on exact = ambiguous).
+    """
+    lowered = name.strip().lower()
+    exact = [e for e in entries if e.name.lower() == lowered]
+    if len(exact) == 1:
+        return exact[0], exact
+    if len(exact) > 1:
+        return None, exact
+    partial = [e for e in entries if lowered in e.name.lower()]
+    if len(partial) == 1:
+        return partial[0], partial
+    return None, partial