ipman-cli 0.1.73__py3-none-any.whl

ipman/hub/client.py

@@ -0,0 +1,132 @@
+"""IpHub client — fetch, cache, and search the index."""
+
+from __future__ import annotations
+
+import time
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_DEFAULT_REPO = "twisker/iphub"
+_DEFAULT_BRANCH = "main"
+_INDEX_URL = (
+    "https://raw.githubusercontent.com"
+    f"/{_DEFAULT_REPO}/{_DEFAULT_BRANCH}/index.yaml"
+)
+_CACHE_TTL_SECONDS = 3600  # 1 hour
+
+
+class IpHubClient:
+    """Client for reading the IpHub reference registry.
+
+    Fetches index.yaml from GitHub, caches locally, and provides
+    search/lookup over the index.
+    """
+
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        index_url: str = _INDEX_URL,
+        base_url: str | None = None,
+    ) -> None:
+        self._base_url = base_url or (
+            "https://raw.githubusercontent.com"
+            f"/{_DEFAULT_REPO}/{_DEFAULT_BRANCH}"
+        )
+        self._index_url = index_url or f"{self._base_url}/index.yaml"
+        self._cache_dir = cache_dir or Path.home() / ".ipman" / "cache"
+        self._cache_file = self._cache_dir / "index.yaml"
+        self._index: dict[str, Any] | None = None
+
+    def fetch_index(
+        self, refresh: bool = False,
+    ) -> dict[str, Any]:
+        """Fetch index.yaml, using local cache if fresh."""
+        if not refresh and self._index is not None:
+            return self._index
+
+        if not refresh and self._cache_file.exists():
+            age = time.time() - self._cache_file.stat().st_mtime
+            if age < _CACHE_TTL_SECONDS:
+                self._index = yaml.safe_load(
+                    self._cache_file.read_text(),
+                )
+                return self._index
+
+        # Fetch from remote
+        with urllib.request.urlopen(self._index_url) as resp:
+            raw = resp.read().decode()
+
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+        self._cache_file.write_text(raw)
+        self._index = yaml.safe_load(raw)
+        return self._index
+
+    def search(
+        self,
+        query: str,
+        agent: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Search index by keyword and optional agent filter."""
+        index = self._index or self.fetch_index()
+        results: list[dict[str, Any]] = []
+        q = query.lower()
+
+        for section in ("skills", "packages"):
+            items = index.get(section, {})
+            for name, info in items.items():
+                if agent and agent not in info.get("agents", []):
+                    continue
+                desc = info.get("description", "").lower()
+                if q and q not in name.lower() and q not in desc:
+                    continue
+                entry = {
+                    "name": name,
+                    "type": info.get("type", section),
+                    **info,
+                }
+                results.append(entry)
+
+        return results
+
+    def lookup(self, name: str) -> dict[str, Any] | None:
+        """Look up a single skill or package by short name."""
+        index = self._index or self.fetch_index()
+        for section in ("skills", "packages"):
+            items = index.get(section, {})
+            if name in items:
+                return {"name": name, **items[name]}
+        return None
+
+    def fetch_registry(
+        self, name: str, version: str | None = None,
+    ) -> dict[str, Any] | None:
+        """Fetch the full registry file for a skill or package.
+
+        For skills: fetches registry/@owner/<name>.yaml
+        For packages: fetches registry/@owner/<name>/<version>.yaml
+                      (defaults to latest version from index)
+        """
+        info = self.lookup(name)
+        if info is None:
+            return None
+
+        owner = info.get("owner", "").lstrip("@")
+        entry_type = info.get("type", "skill")
+
+        if entry_type == "skill":
+            url = self._registry_url(f"@{owner}/{name}.yaml")
+        else:
+            ver = version or info.get("latest", "1.0.0")
+            url = self._registry_url(f"@{owner}/{name}/{ver}.yaml")
+
+        with urllib.request.urlopen(url) as resp:
+            raw = resp.read().decode()
+        result: dict[str, Any] = yaml.safe_load(raw)
+        return result
+
+    def _registry_url(self, path: str) -> str:
+        """Build a URL for a registry file using the configured base."""
+        return f"{self._base_url}/registry/{path}"

ipman/hub/publisher.py

@@ -0,0 +1,274 @@
+"""IpHub publisher — fork, create registry files, submit PR via gh CLI."""
+
+from __future__ import annotations
+
+import base64
+import subprocess
+from datetime import date
+from typing import Any
+
+import yaml
+
+from ipman.core.package import IPPackage
+
+_IPHUB_REPO = "twisker/iphub"
+
+
+def _dump_yaml(data: dict[str, Any]) -> str:
+    """Dump dict to YAML string with standard formatting."""
+    return yaml.dump(
+        data, default_flow_style=False,
+        allow_unicode=True, sort_keys=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class PublishError(Exception):
+    """Raised when a publish operation fails."""
+
+
+# ---------------------------------------------------------------------------
+# GitHub identity
+# ---------------------------------------------------------------------------
+
+def get_github_username() -> str:
+    """Get the authenticated GitHub username via ``gh auth status``."""
+    result = subprocess.run(
+        ["gh", "api", "user", "--jq", ".login"],
+        capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        raise PublishError(
+            "GitHub authentication required. Run `gh auth login` first."
+        )
+    return result.stdout.strip()
+
+
+# ---------------------------------------------------------------------------
+# Registry file generation
+# ---------------------------------------------------------------------------
+
+def generate_skill_registry(
+    *,
+    name: str,
+    description: str,
+    author: str,
+    license_: str | None = None,
+    homepage: str | None = None,
+    keywords: list[str] | None = None,
+    agents: dict[str, dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """Generate a skill registry dict (for registry/@owner/<name>.yaml)."""
+    data: dict[str, Any] = {
+        "type": "skill",
+        "name": name,
+        "description": description,
+        "author": author,
+    }
+    if license_:
+        data["license"] = license_
+    if homepage:
+        data["homepage"] = homepage
+    if keywords:
+        data["keywords"] = keywords
+    if agents:
+        data["agents"] = agents
+    return data
+
+
+def generate_package_registry(
+    *,
+    name: str,
+    description: str,
+    author: str,
+    license_: str | None = None,
+    homepage: str | None = None,
+) -> dict[str, Any]:
+    """Generate a package meta.yaml dict."""
+    data: dict[str, Any] = {
+        "type": "ip",
+        "name": name,
+        "description": description,
+        "author": author,
+    }
+    if license_:
+        data["license"] = license_
+    if homepage:
+        data["homepage"] = homepage
+    return data
+
+
+def generate_version_data(pkg: IPPackage) -> dict[str, Any]:
+    """Generate a package version file dict from an IPPackage."""
+    data: dict[str, Any] = {
+        "version": pkg.version,
+        "released": str(date.today()),
+        "skills": [{"name": s.name} for s in pkg.skills],
+    }
+    if pkg.dependencies:
+        deps = []
+        for d in pkg.dependencies:
+            entry: dict[str, Any] = {"name": d.name}
+            if d.version:
+                entry["version"] = d.version
+            if d.source:
+                entry["source"] = d.source
+            deps.append(entry)
+        data["dependencies"] = deps
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Publisher
+# ---------------------------------------------------------------------------
+
+class IpHubPublisher:
+    """Orchestrates the publish workflow via gh CLI.
+
+    Steps:
+      1. ensure_fork() — fork iphub repo if not already forked
+      2. Create a branch on the fork
+      3. Push registry file(s) to the branch
+      4. Create a PR from fork branch to upstream main
+    """
+
+    def __init__(self, username: str) -> None:
+        self.username = username
+        self.fork_repo = f"{username}/iphub"
+
+    def _gh(self, args: list[str]) -> subprocess.CompletedProcess[str]:
+        """Run a gh CLI command."""
+        result = subprocess.run(
+            ["gh", *args],
+            capture_output=True, text=True, check=False,
+        )
+        if result.returncode != 0:
+            msg = result.stderr.strip() or result.stdout.strip() or "gh command failed"
+            raise PublishError(f"gh error: {msg}")
+        return result
+
+    def ensure_fork(self) -> None:
+        """Fork the iphub repo if not already forked."""
+        self._gh(["repo", "fork", _IPHUB_REPO, "--clone=false"])
+
+    def _push_file(
+        self, branch: str, path: str, content: str, message: str,
+    ) -> None:
+        """Create or update a file on a branch via GitHub API."""
+        encoded = base64.b64encode(content.encode()).decode()
+        self._gh([
+            "api", "-X", "PUT",
+            f"repos/{self.fork_repo}/contents/{path}",
+            "-f", f"message={message}",
+            "-f", f"content={encoded}",
+            "-f", f"branch={branch}",
+        ])
+
+    def _create_branch(self, branch: str) -> None:
+        """Create a branch on the fork from upstream main."""
+        # Get upstream main SHA
+        result = self._gh([
+            "api", f"repos/{_IPHUB_REPO}/git/ref/heads/main",
+            "--jq", ".object.sha",
+        ])
+        sha = result.stdout.strip()
+        # Create branch
+        self._gh([
+            "api", "-X", "POST",
+            f"repos/{self.fork_repo}/git/refs",
+            "-f", f"ref=refs/heads/{branch}",
+            "-f", f"sha={sha}",
+        ])
+
+    def _create_pr(self, branch: str, title: str, body: str) -> str:
+        """Create a PR from fork branch to upstream main."""
+        result = self._gh([
+            "pr", "create",
+            "--repo", _IPHUB_REPO,
+            "--head", f"{self.username}:{branch}",
+            "--base", "main",
+            "--title", title,
+            "--body", body,
+        ])
+        return result.stdout.strip()
+
+    def publish_skill(
+        self,
+        name: str,
+        description: str,
+        agents: dict[str, dict[str, str]] | None = None,
+        license_: str | None = None,
+        homepage: str | None = None,
+        keywords: list[str] | None = None,
+    ) -> str:
+        """Publish a skill to IpHub. Returns PR URL."""
+        self.ensure_fork()
+
+        registry = generate_skill_registry(
+            name=name,
+            description=description,
+            author=f"@{self.username}",
+            license_=license_,
+            homepage=homepage,
+            keywords=keywords,
+            agents=agents,
+        )
+        content = _dump_yaml(registry)
+
+        branch = f"publish/{name}"
+        self._create_branch(branch)
+
+        path = f"registry/@{self.username}/{name}.yaml"
+        self._push_file(
+            branch, path, content, f"Register skill: {name}",
+        )
+
+        return self._create_pr(
+            branch,
+            f"Register skill: {name}",
+            f"Register `{name}` skill by @{self.username}.",
+        )
+
+    def publish_package(self, pkg: IPPackage) -> str:
+        """Publish an IP package to IpHub. Returns PR URL."""
+        self.ensure_fork()
+
+        branch = f"publish/{pkg.name}-v{pkg.version}"
+        self._create_branch(branch)
+
+        # meta.yaml
+        meta = generate_package_registry(
+            name=pkg.name,
+            description=pkg.description,
+            author=f"@{self.username}",
+            license_=pkg.license,
+        )
+        meta_content = _dump_yaml(meta)
+        meta_path = (
+            f"registry/@{self.username}/{pkg.name}/meta.yaml"
+        )
+        self._push_file(
+            branch, meta_path, meta_content,
+            f"Register package: {pkg.name}",
+        )
+
+        # version file
+        version_data = generate_version_data(pkg)
+        version_content = _dump_yaml(version_data)
+        version_path = (
+            f"registry/@{self.username}"
+            f"/{pkg.name}/{pkg.version}.yaml"
+        )
+        self._push_file(
+            branch, version_path, version_content,
+            f"Add {pkg.name} v{pkg.version}",
+        )
+
+        return self._create_pr(
+            branch,
+            f"Register package: {pkg.name} v{pkg.version}",
+            f"Register `{pkg.name}` v{pkg.version} by @{self.username}.",
+        )

ipman/hub/stats.py

@@ -0,0 +1,52 @@
+"""IpHub install statistics reporting via GitHub counter issues."""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime, timezone
+
+_IPHUB_REPO = "twisker/iphub"
+
+
+class StatsError(Exception):
+    """Raised when stats reporting fails."""
+
+
+def report_install(
+    name: str,
+    counter_issue: int,
+    *,
+    username: str | None = None,
+) -> None:
+    """Report a successful install to the counter issue.
+
+    Adds a comment (install count) and a reaction (unique user).
+    Failures raise StatsError but should be treated as non-fatal
+    by callers — install success is independent of stats reporting.
+    """
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    user_part = f" by @{username}" if username else ""
+    body = f"Installed `{name}`{user_part} at {ts}"
+
+    # Add comment
+    result = subprocess.run(
+        [
+            "gh", "issue", "comment", str(counter_issue),
+            "--repo", _IPHUB_REPO,
+            "--body", body,
+        ],
+        capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0:
+        msg = result.stderr.strip() or "Failed to report install stats"
+        raise StatsError(msg)
+
+    # Add reaction (thumbs up) for unique user counting
+    subprocess.run(
+        [
+            "gh", "api", "-X", "POST",
+            f"repos/{_IPHUB_REPO}/issues/{counter_issue}/reactions",
+            "-f", "content=+1",
+        ],
+        capture_output=True, text=True, check=False,
+    )

ipman/utils/i18n.py

@@ -0,0 +1,113 @@
+"""Lightweight i18n — LANG-based Chinese/English auto-switch."""
+
+from __future__ import annotations
+
+import os
+
+_locale: str = "en"
+
+# ---------------------------------------------------------------------------
+# Message catalog
+# ---------------------------------------------------------------------------
+
+_MESSAGES: dict[str, dict[str, str]] = {
+    "install.success": {
+        "en": "Installation complete.",
+        "zh": "安装完成。",
+    },
+    "install.installed": {
+        "en": "Installed '{name}'.",
+        "zh": "已安装 '{name}'。",
+    },
+    "install.failed": {
+        "en": "Install failed: {msg}",
+        "zh": "安装失败：{msg}",
+    },
+    "install.blocked": {
+        "en": "BLOCKED: '{name}' — risk {risk}",
+        "zh": "已阻止：'{name}' — 风险等级 {risk}",
+    },
+    "install.warned": {
+        "en": "WARNING: '{name}' — risk {risk}",
+        "zh": "警告：'{name}' — 风险等级 {risk}",
+    },
+    "uninstall.success": {
+        "en": "Uninstalled '{name}'.",
+        "zh": "已卸载 '{name}'。",
+    },
+    "pack.success": {
+        "en": "Packed {count} skill(s) into {path}",
+        "zh": "已将 {count} 个技能打包到 {path}",
+    },
+    "hub.search.no_results": {
+        "en": "No results found.",
+        "zh": "未找到结果。",
+    },
+    "hub.publish.blocked": {
+        "en": "Publish blocked: HIGH/EXTREME risk.",
+        "zh": "发布被阻止：风险等级为 HIGH/EXTREME。",
+    },
+    "hub.report.success": {
+        "en": "Reported '{name}'. Thank you for helping keep IpHub safe.",
+        "zh": "已举报 '{name}'。感谢您帮助维护 IpHub 安全。",
+    },
+    "env.created": {
+        "en": "Created environment '{name}'.",
+        "zh": "已创建环境 '{name}'。",
+    },
+    "env.activated": {
+        "en": "Activated environment '{name}'.",
+        "zh": "已激活环境 '{name}'。",
+    },
+    "env.deactivated": {
+        "en": "Deactivated environment.",
+        "zh": "已停用环境。",
+    },
+    "error.no_agent": {
+        "en": "No agent detected. Use --agent to specify one.",
+        "zh": "未检测到 Agent 工具。请使用 --agent 指定。",
+    },
+    "error.not_found": {
+        "en": "'{name}' not found.",
+        "zh": "未找到 '{name}'。",
+    },
+    "security.log_entry": {
+        "en": "{action} {name} source={source} risk={risk}",
+        "zh": "{action} {name} 来源={source} 风险={risk}",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# API
+# ---------------------------------------------------------------------------
+
+def detect_locale() -> str:
+    """Detect locale from environment variables."""
+    for var in ("LC_ALL", "LANG", "LANGUAGE"):
+        val = os.environ.get(var, "")
+        if val.startswith("zh"):
+            return "zh"
+    return "en"
+
+
+def set_locale(locale: str) -> None:
+    """Manually set the active locale."""
+    global _locale  # noqa: PLW0603
+    _locale = locale
+
+
+def get_locale() -> str:
+    """Get the current active locale."""
+    return _locale
+
+
+def t(key: str, **kwargs: str | int) -> str:
+    """Translate a message key with optional format args."""
+    messages = _MESSAGES.get(key)
+    if messages is None:
+        return key
+    template = messages.get(_locale, messages.get("en", key))
+    if kwargs:
+        return template.format(**kwargs)
+    return template

ipman/utils/symlink.py

@@ -0,0 +1,84 @@
+"""Cross-platform symlink utilities."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def create_symlink(target: Path, link: Path) -> None:
+    """Create a symlink at `link` pointing to `target`.
+
+    On Windows, uses directory junctions as a fallback if symlinks
+    require elevated privileges.
+    """
+    target = target.resolve()
+    _validate_no_traversal(target)
+
+    if link.exists() or link.is_symlink():
+        msg = f"Link path already exists: {link}"
+        raise FileExistsError(msg)
+
+    if sys.platform == "win32":
+        _create_windows_link(target, link)
+    else:
+        link.symlink_to(target)
+
+
+def remove_symlink(link: Path) -> None:
+    """Remove a symlink (or junction on Windows).
+
+    Raises ValueError if the path is not a symlink.
+    """
+    if not link.is_symlink():
+        if sys.platform == "win32" and link.is_dir():
+            # Could be a junction on Windows
+            os.rmdir(link)
+            return
+        msg = f"Not a symlink: {link}"
+        raise ValueError(msg)
+    link.unlink()
+
+
+def is_symlink(path: Path) -> bool:
+    """Check if path is a symlink (or junction on Windows)."""
+    if path.is_symlink():
+        return True
+    if sys.platform == "win32" and path.is_dir():
+        # Check for junction point
+        try:
+            return bool(os.readlink(path))
+        except OSError:
+            return False
+    return False
+
+
+def resolve_symlink(path: Path) -> Path | None:
+    """Return the target of a symlink, or None if not a symlink."""
+    if is_symlink(path):
+        return Path(os.readlink(path))
+    return None
+
+
+def _validate_no_traversal(target: Path) -> None:
+    """Validate that the resolved target doesn't traverse outside expectations."""
+    resolved = target.resolve()
+    if ".." in resolved.parts:
+        msg = f"Path traversal detected: {target}"
+        raise ValueError(msg)
+
+
+def _create_windows_link(target: Path, link: Path) -> None:
+    """Create a symlink or directory junction on Windows."""
+    try:
+        link.symlink_to(target)
+    except OSError:
+        # Fallback to directory junction (no admin needed)
+        import subprocess
+
+        subprocess.run(
+            ["cmd", "/c", "mklink", "/J", str(link), str(target)],
+            check=True,
+            capture_output=True,
+        )