@adgine/geo-cli 1.2.8

package/skills/adgine-geo-wordpress/scripts/publish.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Publish a GEO content item (or raw markdown) to WordPress.
+
+Two modes:
+  --content-id <uuid>           — publish an existing system article by ID
+  --title <t> --content-body <md>
+                                — publish raw title + markdown body
+
+Optional:
+  --category-ids 1,2,3          — WP category IDs (omitted → Uncategorized)
+  --status publish|draft        — publish state (default: publish)
+
+Examples:
+  python3 scripts/publish.py --content-id <uuid> --category-ids 2,5
+  python3 scripts/publish.py --title "My Post" --content-body "# Hello..." --status draft
+
+Run list_publishable.py first to find content_id candidates.
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_post, extract_data, print_json,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Publish content to WordPress")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    parser.add_argument("--content-id", help="System article UUID (content_id mode)")
+    parser.add_argument("--title", help="Article title (direct mode)")
+    parser.add_argument("--content-body", help="Markdown body (direct mode)")
+    parser.add_argument("--category-ids", help="Comma-separated WP category IDs")
+    parser.add_argument("--status", default="publish",
+                        choices=["publish", "draft"],
+                        help="Publish state (default: publish)")
+    args = parser.parse_args()
+
+    if not args.content_id and not (args.title and args.content_body):
+        print("ERROR: provide either --content-id OR both --title and --content-body.")
+        sys.exit(1)
+
+    body = {"status": args.status}
+    if args.content_id:
+        body["content_id"] = args.content_id
+    else:
+        body["title"] = args.title
+        body["content_body"] = args.content_body
+    if args.category_ids:
+        body["category_ids"] = [
+            int(c.strip()) for c in args.category_ids.split(",") if c.strip()
+        ]
+
+    key, base = get_api_config()
+    pid = get_project_id(args.project_id)
+
+    result = api_post(
+        f"/api/projects/{pid}/integrations/wordpress/publish",
+        key, base, body=body,
+    )
+    data = extract_data(result) or {}
+
+    if args.json:
+        print_json(data)
+        return
+
+    print("Published to WordPress.")
+    for k in ("record_id", "wp_post_id", "wp_post_url", "status",
+              "published_at"):
+        if k in data:
+            print(f"  {k}: {data.get(k)}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/scripts/check_version.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""
+Check whether a newer version of adgine-geo-skills is available on GitHub.
+
+The canonical VERSION source of truth is:
+  https://github.com/adgine-ai/adgine-geo-skills/blob/main/VERSION
+fetched via the raw endpoint.
+
+Two output modes:
+  (default)   Print a JSON object describing the version state.
+  --notice    Print a single `_notice: {...}` line IF (and only if) an update
+              is available. Prints nothing otherwise. This is what scripts emit
+              at startup so the AI agent sees it in the tool output and prompts
+              the user to update.
+  --footer    Print a human-readable `---` / ⚠️ footer IF an update is available.
+  --human     Print a one-line Chinese update hint for agents (WorkBuddy). Empty if up to date.
+
+Exits 0 always — any error (network, parse, etc.) is silently suppressed so the
+calling skill's main flow is never blocked.
+
+Debug (opt-in, does not change exit code):
+  GEO_VERSION_CHECK_DEBUG=1   Log failures to stderr.
+  --verbose                 Same, with default or --notice mode.
+
+JSON schema (default mode):
+  {
+    "current": "1.1.0",
+    "latest": "1.2.0",
+    "update_available": true,
+    "install_type": "git" | "package",
+    "update_command": "git -C /path/to/dir pull",   // git only
+    "release_url": "https://github.com/..."
+  }
+"""
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+VERSION_FILE = os.path.join(REPO_ROOT, "VERSION")
+REMOTE_VERSION_URL = (
+    "https://raw.githubusercontent.com/adgine-ai/adgine-geo-skills/main/VERSION"
+)
+RELEASE_URL = "https://github.com/adgine-ai/adgine-geo-skills/releases/latest"
+TIMEOUT = 5
+# Cache the remote version lookup so a conversation that runs several scripts
+# in one turn does not hammer GitHub. A fresh conversation later still re-checks
+# once the cache expires.
+CACHE_TTL = 120  # 2 minutes — dedupes a burst of scripts in one turn while
+# still surfacing a freshly-pushed version within ~2 min.
+CACHE_FILE = os.path.join(tempfile.gettempdir(), "adgine_geo_skills_version.json")
+
+
+def _debug_enabled():
+    return os.environ.get("GEO_VERSION_CHECK_DEBUG") == "1" or "--verbose" in sys.argv
+
+
+def _debug(msg):
+    if _debug_enabled():
+        print(f"[check_version] {msg}", file=sys.stderr)
+
+
+def _read_version_from_skill_md():
+    """Fallback when installers (e.g. WorkBuddy) omit the root VERSION file."""
+    skill_md = os.path.join(REPO_ROOT, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        return None
+    in_frontmatter = False
+    with open(skill_md, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line == "---":
+                in_frontmatter = not in_frontmatter
+                if not in_frontmatter:
+                    break
+                continue
+            if in_frontmatter:
+                m = re.match(r'^version:\s*["\']?([^"\'#\s]+)', line)
+                if m:
+                    return m.group(1).strip()
+    return None
+
+
+def _read_local_version():
+    if os.path.isfile(VERSION_FILE):
+        with open(VERSION_FILE) as f:
+            return f.read().strip()
+    fallback = _read_version_from_skill_md()
+    if fallback:
+        _debug(f"VERSION file missing; using SKILL.md frontmatter ({fallback})")
+        return fallback
+    raise FileNotFoundError(VERSION_FILE)
+
+
+def _fetch_remote_version():
+    """Return the latest version string from GitHub, using a short-lived cache."""
+    # Serve from cache if fresh
+    try:
+        with open(CACHE_FILE) as f:
+            cached = json.load(f)
+        if time.time() - cached.get("ts", 0) < CACHE_TTL and cached.get("latest"):
+            return cached["latest"]
+    except Exception:
+        pass
+
+    req = urllib.request.Request(
+        f"{REMOTE_VERSION_URL}?t={int(time.time())}",
+        headers={
+            "User-Agent": "adgine-geo-skills-version-check/1.0",
+            "Cache-Control": "no-cache",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+        latest = resp.read().decode().strip()
+
+    try:
+        with open(CACHE_FILE, "w") as f:
+            json.dump({"ts": time.time(), "latest": latest}, f)
+    except Exception:
+        pass
+    return latest
+
+
+def _parse_version(v):
+    """Return tuple of ints for semver comparison, e.g. 'v1.2.3' → (1, 2, 3)."""
+    return tuple(int(x) for x in v.strip().lstrip("v").split("."))
+
+
+def _is_git_repo(path):
+    try:
+        result = subprocess.run(
+            ["git", "-C", path, "rev-parse", "--git-dir"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=3,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def get_state():
+    """Return the full version-state dict, or None on any error.
+
+    Returns None immediately when GEO_SKIP_VERSION_CHECK is set. The npm CLI
+    (adgine-geo) sets this so version updates are surfaced by npm instead, and
+    so stdout stays clean (no `_notice:`/footer lines) and no per-command
+    network round-trip to GitHub is incurred.
+    """
+    if os.environ.get("GEO_SKIP_VERSION_CHECK"):
+        return None
+    try:
+        current = _read_local_version()
+        latest = _fetch_remote_version()
+        update_available = _parse_version(latest) > _parse_version(current)
+        is_git = _is_git_repo(REPO_ROOT)
+        return {
+            "current": current,
+            "latest": latest,
+            "update_available": update_available,
+            "install_type": "git" if is_git else "package",
+            "update_command": f"git -C {REPO_ROOT} pull" if is_git else "",
+            "release_url": RELEASE_URL,
+        }
+    except Exception as exc:
+        _debug(f"check failed: {exc}")
+        return None
+
+
+def format_user_footer(state):
+    """Human-readable update block for stdout (WorkBuddy and similar agents).
+
+    Printed at the end of script output so agents that rewrite tool results
+    still surface the message when they quote trailing lines.
+    """
+    if not state or not state.get("update_available"):
+        return ""
+    cur, lat = state["current"], state["latest"]
+    if state.get("install_type") == "git":
+        body = (
+            f"⚠️ adgine-geo-skills v{lat} 已发布（当前 v{cur}）。"
+            "跟我说「请帮我更新 adgine-geo-skills 到最新版本」即可升级。"
+        )
+    else:
+        url = state.get("release_url", "")
+        body = (
+            f"⚠️ adgine-geo-skills v{lat} 已发布（当前 v{cur}）。"
+            f"请前往 {url} 下载最新版并重新安装。"
+        )
+    return f"---\n{body}"
+
+
+def format_user_inline(state):
+    """One-line update hint (matches Hermes-style phrasing for WorkBuddy)."""
+    if not state or not state.get("update_available"):
+        return ""
+    cur, lat = state["current"], state["latest"]
+    if state.get("install_type") == "git":
+        return (
+            f"另外 adgine-geo-skills 又有新版本 v{lat}（当前 v{cur}），需要更新吗？"
+            "跟我说「请帮我更新 adgine-geo-skills 到最新版本」即可升级。"
+        )
+    url = state.get("release_url", "")
+    return (
+        f"另外 adgine-geo-skills 又有新版本 v{lat}（当前 v{cur}），需要更新吗？"
+        f"请前往 {url} 下载最新版并重新安装。"
+    )
+
+
+def emit_human(stream=None):
+    """Print a single-line human hint; empty when up to date."""
+    stream = stream or sys.stdout
+    line = format_user_inline(get_state())
+    if not line:
+        return
+    try:
+        stream.write(line + "\n")
+        stream.flush()
+    except Exception:
+        pass
+
+
+def emit_footer(stream=None):
+    """Print the human-readable footer if an update is available."""
+    stream = stream or sys.stdout
+    footer = format_user_footer(get_state())
+    if not footer:
+        return
+    try:
+        stream.write(footer + "\n")
+        stream.flush()
+    except Exception:
+        pass
+
+
+def emit_notice(stream=None):
+    """Print a single `_notice:` line to `stream` if an update is available.
+
+    Writes to STDOUT by default so the agent harness reliably surfaces it in the
+    tool result (some harnesses only feed stdout to the model). The `_notice:`
+    prefix lets agents parse it before JSON on the same stream.
+
+    Silent when up to date or on any error. Safe to call at the top of any
+    skill script — never raises, never blocks.
+    """
+    stream = stream or sys.stdout
+    state = get_state()
+    if not state or not state.get("update_available"):
+        return
+    cur, lat = state["current"], state["latest"]
+    if state.get("install_type") == "git":
+        msg = (f"adgine-geo-skills {lat} available (current {cur}). "
+               "Tell me: 请帮我更新 adgine-geo-skills 到最新版本")
+    else:
+        msg = (f"adgine-geo-skills {lat} available (current {cur}). "
+               f"Download: {state.get('release_url', '')}")
+    notice = {"update": {"current": cur, "latest": lat, "message": msg}}
+    try:
+        stream.write(f"_notice: {json.dumps(notice, ensure_ascii=False)}\n\n")
+        stream.flush()
+    except Exception:
+        pass
+
+
+def main():
+    if "--notice" in sys.argv:
+        emit_notice()
+        sys.exit(0)
+    if "--footer" in sys.argv:
+        emit_footer()
+        sys.exit(0)
+    if "--human" in sys.argv:
+        emit_human()
+        sys.exit(0)
+    state = get_state()
+    if state is not None:
+        print(json.dumps(state, ensure_ascii=False))
+    elif _debug_enabled():
+        _debug("no state returned (see errors above)")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/setup.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Setup helper for adgine-geo-skills.
+
+Two ways to run:
+
+  Non-interactive (for AI agents / scripts):
+      python3 setup.py <GEO_API_KEY>
+      python3 setup.py --key <GEO_API_KEY>
+
+  Interactive wizard (for humans):
+      python3 setup.py
+
+Behavior:
+  - Locates the skills repo root via this file's own absolute path,
+    so it works regardless of the caller's current working directory.
+  - Writes GEO_API_KEY to <repo_root>/.env (creating it from
+    .env.example if needed). Preserves other lines in .env.
+  - Verifies the key by calling /api/projects?limit=1 with Bearer auth.
+    Exit code 0 on success, non-zero on failure.
+  - Never writes to ~/.zshrc, ~/.bashrc, ~/.hermes/, or any other
+    location. The .env file is gitignored — the key stays local.
+"""
+import os
+import sys
+import shutil
+import argparse
+import atexit
+import importlib.util
+
+REPO_ROOT = os.path.dirname(os.path.abspath(__file__))
+ENV_PATH = os.path.join(REPO_ROOT, ".env")
+ENV_EXAMPLE_PATH = os.path.join(REPO_ROOT, ".env.example")
+PLACEHOLDER_VALUES = {"", "geo_sk_live_YOUR_KEY_HERE", "geo_sk...HERE"}
+
+
+def _load_check_version_module():
+    path = os.path.join(REPO_ROOT, "scripts", "check_version.py")
+    if not os.path.isfile(path):
+        return None
+    spec = importlib.util.spec_from_file_location("geo_check_version", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _emit_version_notice():
+    try:
+        mod = _load_check_version_module()
+        if mod is not None:
+            mod.emit_notice()
+    except Exception:
+        pass
+
+
+def _emit_version_footer():
+    try:
+        mod = _load_check_version_module()
+        if mod is not None:
+            mod.emit_footer()
+    except Exception:
+        pass
+
+
+atexit.register(_emit_version_footer)
+
+
+def read_env_key():
+    """Return the current GEO_API_KEY from .env, or None if unset/placeholder."""
+    if not os.path.isfile(ENV_PATH):
+        return None
+    with open(ENV_PATH) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith("GEO_API_KEY="):
+                val = line.split("=", 1)[1].strip()
+                return val if val not in PLACEHOLDER_VALUES else None
+    return None
+
+
+def write_env_key(key):
+    """Write or update GEO_API_KEY in <repo_root>/.env, preserving other lines."""
+    if not os.path.isfile(ENV_PATH):
+        if os.path.isfile(ENV_EXAMPLE_PATH):
+            shutil.copy(ENV_EXAMPLE_PATH, ENV_PATH)
+        else:
+            with open(ENV_PATH, "w") as f:
+                f.write("# GEO Skills — Environment Variables\n")
+
+    with open(ENV_PATH) as f:
+        lines = f.readlines()
+
+    found = False
+    new_lines = []
+    for line in lines:
+        if line.strip().startswith("GEO_API_KEY="):
+            new_lines.append(f"GEO_API_KEY={key}\n")
+            found = True
+        else:
+            new_lines.append(line)
+    if not found:
+        if new_lines and not new_lines[-1].endswith("\n"):
+            new_lines.append("\n")
+        new_lines.append(f"GEO_API_KEY={key}\n")
+
+    with open(ENV_PATH, "w") as f:
+        f.writelines(new_lines)
+
+
+def verify_key(key):
+    """Quick auth check. Returns (ok: bool, message: str).
+
+    ok=True means the key is accepted (HTTP 200) OR the platform was
+    unreachable (we don't want to block setup on transient network issues).
+    ok=False means we got a definitive 401 Unauthorized.
+    """
+    import urllib.request as req
+    import urllib.error as uerr
+
+    base = os.environ.get("GEO_API_BASE_URL", "https://platform.adgine.ai").rstrip("/")
+    url = f"{base}/api/projects?limit=1"
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Accept": "application/json",
+        "User-Agent": "geo-skills-setup/1.0",
+    }
+    request = req.Request(url, headers=headers, method="GET")
+    try:
+        with req.urlopen(request, timeout=10) as resp:
+            return (resp.status == 200, f"HTTP {resp.status}")
+    except uerr.HTTPError as e:
+        if e.code == 401:
+            return (False, "401 Unauthorized — key is invalid")
+        # Other errors (403, 5xx) don't necessarily mean the key is wrong.
+        return (True, f"HTTP {e.code} (non-auth error, treating as ok)")
+    except Exception as e:
+        return (True, f"network error: {e} (skipped verification)")
+
+
+def print_next_steps():
+    print("  Next steps:")
+    print("  1. List your projects:")
+    print("       python3 adgine-geo-projects/scripts/list_projects.py")
+    print("  2. Ask your agent, for example:")
+    print('       "What\'s my AI visibility score this week?"')
+    print()
+
+
+def run_noninteractive(key):
+    """Install the key without prompting. Used by AI agents."""
+    if not key or key in PLACEHOLDER_VALUES:
+        print("ERROR: empty or placeholder key.", file=sys.stderr)
+        sys.exit(2)
+
+    if not key.startswith("geo_sk_"):
+        print(
+            f"WARNING: key does not start with 'geo_sk_' (got: {key[:8]}...). "
+            "Continuing anyway.",
+            file=sys.stderr,
+        )
+
+    ok, detail = verify_key(key)
+    if not ok:
+        print(f"ERROR: key verification failed — {detail}", file=sys.stderr)
+        print("  Check the key at: https://platform.adgine.ai", file=sys.stderr)
+        sys.exit(1)
+
+    write_env_key(key)
+    print(f"OK: GEO_API_KEY written to {ENV_PATH}")
+    print(f"    verification: {detail}")
+    sys.exit(0)
+
+
+def run_interactive():
+    """Wizard for human users."""
+    print()
+    print("=" * 52)
+    print("  adgine-geo-skills — Setup Wizard")
+    print("=" * 52)
+    print()
+
+    existing_key = read_env_key()
+
+    if existing_key:
+        print(f"  GEO_API_KEY already set in {ENV_PATH}")
+        print()
+        answer = input("  Re-enter / update it? [y/N] ").strip().lower()
+        if answer != "y":
+            print()
+            print("  No changes made. You're ready to go!")
+            print()
+            print_next_steps()
+            return
+
+    print("  Get your API key at: https://platform.adgine.ai")
+    print()
+    key = input("  Paste your GEO_API_KEY: ").strip()
+
+    if not key or key in PLACEHOLDER_VALUES:
+        print()
+        print("  No key entered. Run setup.py again when you have your key.")
+        sys.exit(1)
+
+    print()
+    print("  Verifying key...", end="", flush=True)
+    ok, detail = verify_key(key)
+    if ok:
+        print(f" OK ({detail})")
+    else:
+        print(f" FAILED ({detail})")
+        print()
+        print("  Double-check at: https://platform.adgine.ai")
+        sys.exit(1)
+
+    write_env_key(key)
+    print()
+    print(f"  Key saved to: {ENV_PATH}")
+    print("  (This file is gitignored — your key stays local and private.)")
+    print()
+    print_next_steps()
+
+
+def main():
+    _emit_version_notice()
+    parser = argparse.ArgumentParser(
+        description="Configure GEO_API_KEY for adgine-geo-skills.",
+        add_help=True,
+    )
+    parser.add_argument(
+        "key",
+        nargs="?",
+        help="GEO_API_KEY to install. Omit for interactive mode.",
+    )
+    parser.add_argument(
+        "--key",
+        dest="key_flag",
+        help="GEO_API_KEY (alternative to positional argument).",
+    )
+    args = parser.parse_args()
+
+    key = args.key_flag or args.key
+    if key:
+        run_noninteractive(key)
+    else:
+        run_interactive()
+
+
+if __name__ == "__main__":
+    main()