n-seo 0.1.0

package/ops/doctor.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Setup checker: is this install ready to run?
+
+  python3 ops/doctor.py            # everything, including live Google calls
+  python3 ops/doctor.py --offline  # local checks only
+
+Each check prints OK / WARN / FAIL with a fix hint. Exit code 1 on any FAIL.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ingest"))
+import seo_config  # noqa: E402
+
+OFFLINE = "--offline" in sys.argv
+FAILS = 0
+
+
+def report(level, name, detail=""):
+    global FAILS
+    if level == "FAIL":
+        FAILS += 1
+    print(f"  {level:4s} {name}" + (f" — {detail}" if detail else ""))
+
+
+def check_engine():
+    e = seo_config.engine_info()
+    print("engine")
+    report("OK", f"n-seo {e['version']}" + (f" · {e['commit']}" if e["commit"] else ""))
+    report("OK", f"mode: {e['mode']}", "" if e["mode"] == "instance"
+           else "config, queue and data live inside the engine checkout (see docs/INSTANCE.md to split them)")
+    report("OK", f"engine: {e['root']}")
+    report("OK", f"instance: {e['instance']}")
+
+
+def check_config():
+    print("config")
+    if seo_config.using_example():
+        report("WARN", "n-seo.config.json missing",
+               "running on the example — copy n-seo.config.example.json to "
+               "n-seo.config.json or open /settings in the dashboard")
+    else:
+        report("OK", f"config at {seo_config.CONFIG_PATH}")
+    try:
+        cfg = seo_config.load(force=True)
+    except json.JSONDecodeError as exc:
+        report("FAIL", "config is not valid JSON", str(exc))
+        return None
+    sites = cfg["sites"]
+    if not sites:
+        report("FAIL", "no sites configured", "add at least one entry to sites[]")
+    else:
+        report("OK", f"{len(sites)} site(s): {', '.join(s['host'] for s in sites)}")
+    for s in sites:
+        if not s.get("gscProperty") and not s.get("ga4Property"):
+            report("WARN", f"{s['host']} has neither gscProperty nor ga4Property",
+                   "it will be probed but have no search or traffic data")
+    return cfg
+
+
+def check_tools():
+    print("tools")
+    for tool, why in (("curl", "all HTTP goes through curl"), ("openssl", "signs the service-account JWT")):
+        report("OK" if shutil.which(tool) else "FAIL", tool, "" if shutil.which(tool) else f"install it — {why}")
+    v = sys.version_info
+    report("OK" if v >= (3, 10) else "FAIL", f"python {v.major}.{v.minor}",
+           "" if v >= (3, 10) else "3.10+ required")
+    nm = seo_config.ROOT / "node_modules"
+    report("OK" if nm.exists() else "WARN", "node_modules", "" if nm.exists() else "run: npm install")
+
+
+def check_auth(cfg):
+    print("google auth")
+    g = cfg["google"]
+    mode = g.get("auth", "service-account-key")
+    report("OK", f"mode: {mode}")
+    import google_auth
+    if mode == "service-account-key":
+        kp = google_auth.key_path()
+        if not kp or not Path(kp).exists():
+            report("FAIL", "service-account key file not found",
+                   f"{kp or '(unset)'} — set google.serviceAccountKey or $GOOGLE_APPLICATION_CREDENTIALS; see docs/SETUP-GOOGLE.md")
+            return None
+        try:
+            key = json.loads(Path(kp).read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            report("FAIL", "key file unreadable", str(exc))
+            return None
+        if not key.get("client_email") or not key.get("private_key"):
+            report("FAIL", "key file lacks client_email/private_key", "download a fresh JSON key for the service account")
+            return None
+        report("OK", f"key for {key['client_email']}")
+    elif mode == "metadata":
+        # Only meaningful on GCE / Cloud Run / GKE; say so plainly elsewhere
+        # rather than leaving a confusing token failure as the only clue.
+        email = g.get("impersonate") or google_auth.metadata_service_account()
+        if not email:
+            report("FAIL", "no metadata server on this machine",
+                   "google.auth is metadata, which needs GCE, Cloud Run or GKE — "
+                   "use service-account-key elsewhere; see docs/SETUP-GOOGLE.md")
+            return None
+        report("OK", f"runtime service account {email}")
+    else:
+        if not shutil.which("gcloud"):
+            report("FAIL", "gcloud not on PATH", "install the Google Cloud SDK or switch to service-account-key")
+            return None
+        if mode == "gcloud-impersonate" and not g.get("impersonate"):
+            report("FAIL", "google.impersonate is empty", "set the service-account email to impersonate")
+            return None
+        report("OK", "gcloud present")
+    if OFFLINE:
+        return None
+    try:
+        tok = google_auth.access_token(google_auth.WEBMASTERS_RO)
+        report("OK", "minted a Search Console token")
+        return tok
+    except Exception as exc:  # noqa: BLE001
+        report("FAIL", "could not mint a token", str(exc)[:200])
+        return None
+
+
+def check_gsc(cfg, tok):
+    print("search console")
+    props = seo_config.gsc_properties()
+    if not props:
+        report("WARN", "no gscProperty configured")
+        return
+    if OFFLINE or not tok:
+        report("WARN", "skipped (offline or no token)")
+        return
+    from http_util import get_json
+    import google_auth
+    try:
+        resp = get_json("https://searchconsole.googleapis.com/webmasters/v3/sites", tok, label="sites")
+    except RuntimeError as exc:
+        report("FAIL", "sites list failed", str(exc)[:200])
+        return
+    have = {e["siteUrl"]: e.get("permissionLevel") for e in resp.get("siteEntry", []) if "siteUrl" in e}
+    who = google_auth.service_account_email() or "your account"
+    for p in props:
+        if p in have:
+            report("OK", f"{p} ({have[p]})")
+        else:
+            report("FAIL", f"{p} not accessible",
+                   f"in Search Console add {who} as a Full user on that property (or verify the property first)")
+
+
+def check_ga4(cfg, tok_unused):
+    print("ga4")
+    props = seo_config.ga4_properties()
+    if not props:
+        report("WARN", "no ga4Property configured")
+        return
+    if OFFLINE:
+        report("WARN", "skipped (offline)")
+        return
+    import google_auth
+    from http_util import post_json
+    try:
+        tok = google_auth.access_token(google_auth.ANALYTICS_RO)
+    except Exception as exc:  # noqa: BLE001
+        report("FAIL", "could not mint an Analytics token", str(exc)[:200])
+        return
+    who = google_auth.service_account_email() or "your account"
+    for host, prop in props.items():
+        try:
+            r = post_json(f"https://analyticsdata.googleapis.com/v1beta/properties/{prop}:runReport",
+                          {"dateRanges": [{"startDate": "yesterday", "endDate": "yesterday"}],
+                           "metrics": [{"name": "sessions"}]}, tok, label=f"ga4 {prop}")
+        except RuntimeError as exc:
+            report("FAIL", f"{host} (properties/{prop})", str(exc)[:200])
+            continue
+        if r.get("error"):
+            report("FAIL", f"{host} (properties/{prop})",
+                   f"{r['error'].get('message', '')[:120]} — add {who} as Viewer on the GA4 property")
+        else:
+            report("OK", f"{host} (properties/{prop})")
+
+
+def check_dashboard():
+    print("dashboard")
+    if OFFLINE:
+        report("WARN", "skipped (offline)")
+        return
+    base = seo_config.dashboard_base()
+    p = subprocess.run(["curl", "-sf", "--max-time", "5", base + "/api/actions"], capture_output=True)
+    report("OK" if p.returncode == 0 else "WARN", base, "" if p.returncode == 0 else "not running — npm start")
+
+
+def check_modules(cfg):
+    print("modules")
+    on = [k for k, v in cfg["modules"].items() if v.get("enabled")]
+    report("OK", "enabled: " + (", ".join(on) or "(none beyond defaults)"))
+    llm = cfg["modules"].get("llm", {})
+    if llm.get("enabled"):
+        import shlex
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import llm as llm_mod
+        http = llm_mod.http_config()
+        if http:
+            report("OK", f"llm over http: {http['provider']} {http['model']}")
+            fast = llm_mod.http_config(fast=True)
+            if fast and fast["model"] != http["model"]:
+                report("OK", f"llm fast model: {fast['model']}")
+        elif isinstance(llm.get("http"), dict) and llm["http"]:
+            report("FAIL", "llm.http is configured but unusable",
+                   f"check provider/model and that {llm['http'].get('apiKeyEnv') or 'apiKeyEnv'} "
+                   "is set in the environment or .env")
+        for key in ("command", "fastCommand"):
+            cmd = shlex.split(str(llm.get(key) or ""))
+            if not cmd:
+                # Only complain about a missing command when there is no http
+                # block at all; a broken one already reported itself.
+                if key == "command" and not http and not llm.get("http"):
+                    report("FAIL", "llm has neither http nor command configured")
+                continue
+            report("OK" if shutil.which(cmd[0]) else "FAIL", f"llm.{key}: {cmd[0]}",
+                   "" if shutil.which(cmd[0]) else "not on PATH")
+    hn = cfg["modules"].get("hackerNews", {})
+    if hn.get("enabled"):
+        user = (hn.get("user") or "").strip()
+        if not user:
+            report("WARN", "hackerNews.user empty", "threads you already joined won't be marked")
+        elif not OFFLINE:
+            from http_util import get_json
+            try:
+                prof = get_json(f"https://hacker-news.firebaseio.com/v0/user/{user}.json", label="hn user")
+                report("OK" if prof else "FAIL", f"HN user {user}", "" if prof else "profile not found")
+            except RuntimeError as exc:
+                report("WARN", f"HN user {user}", str(exc)[:120])
+        if not hn.get("topics"):
+            report("WARN", "hackerNews.topics empty", "add [query, why] pairs")
+        if not (cfg["participation"] or {}).get("expertise", "").strip():
+            report("WARN", "participation.expertise empty", "briefings will be skipped")
+    rd = cfg["modules"].get("reddit", {})
+    if rd.get("enabled"):
+        ok = bool(seo_config.env("REDDIT_CLIENT_ID") and seo_config.env("REDDIT_CLIENT_SECRET"))
+        report("OK" if ok else "FAIL", "reddit credentials",
+               "" if ok else "REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET missing from .env")
+    if cfg["modules"].get("indexNow", {}).get("enabled"):
+        kf = cfg["modules"]["indexNow"].get("keyFile") or "indexnow.key"
+        p = Path(kf) if Path(kf).is_absolute() else seo_config.INSTANCE / kf
+        report("OK" if p.exists() else "WARN", f"indexNow key {kf}", "" if p.exists() else "run: python3 ops/indexnow.py init")
+
+
+def main():
+    check_engine()
+    cfg = check_config()
+    check_tools()
+    if cfg is None:
+        return 1
+    tok = check_auth(cfg)
+    check_gsc(cfg, tok)
+    check_ga4(cfg, tok)
+    check_dashboard()
+    check_modules(cfg)
+    print(f"\n{'all good' if not FAILS else f'{FAILS} problem(s) to fix'}")
+    return 1 if FAILS else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/ops/export_static.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Snapshot the running dashboard into site/ as static HTML (modules.staticExport).
+
+Host site/ anywhere you like — behind your own login, on an internal box, in
+a private bucket. All data collection stays on the machine that runs the
+daily job; the export is a read-only mirror of what the dashboard showed.
+
+Every exported page gets a noindex meta and the export writes a deny-all
+robots.txt: this is an internal ops view, not public content. Pages also
+carry a small script that shows a banner when the mirror is more than 36
+hours old, so a stalled daily job is visible from the mirror itself.
+"""
+
+import html as html_mod
+import re
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ingest"))
+import seo_config  # noqa: E402
+
+ROOT = seo_config.ROOT
+INSTANCE = seo_config.INSTANCE
+SITE = INSTANCE / "site"
+BASE = seo_config.dashboard_base()
+
+
+def routes():
+    hosts = seo_config.hosts()
+    drafts_dir = INSTANCE / "content" / "drafts"
+    camps_dir = INSTANCE / "content" / "campaigns"
+    # Same filter as the dashboard's drafts()/campaigns(): README and _-prefixed files are not content.
+    skip = lambda p: p.name.lower() == "readme.md" or p.name.startswith("_")
+    drafts = sorted(p.stem for p in drafts_dir.glob("*.md") if not skip(p)) if drafts_dir.exists() else []
+    camps = sorted(p.stem for p in camps_dir.glob("*.json") if not skip(p)) if camps_dir.exists() else []
+    return (["/", "/actions", "/insights", "/trends", "/trends/30", "/trends/60", "/trends/90",
+             # /settings is deliberately absent: it shows local paths and the
+             # service-account email, and its form cannot work on a static mirror.
+             "/trends/120", "/trends/180", "/content", "/indexing", "/probes", "/logs"]
+            + [f"/site/{h}" for h in hosts]
+            + [f"/drafts/{s}" for s in drafts]
+            + [f"/campaigns/{s}" for s in camps])
+
+
+# hono/jsx renders the slot without whitespace, but match loosely so a
+# future formatting change cannot silently drop the sign-out link.
+EXPORT_SLOT = re.compile(r'<span id="export-slot"\s*>\s*</span>')
+
+
+def sign_out_link() -> str:
+    """The <a> that replaces the export slot, or "" when unconfigured.
+
+    Any auth proxy will do — IAP, Cloudflare Access, oauth2-proxy — so this
+    is just a URL the operator supplies.
+    """
+    m = seo_config.module("staticExport")
+    url = (m.get("signOutUrl") or "").strip()
+    if not url:
+        return ""
+    label = (m.get("signOutLabel") or "Sign out").strip() or "Sign out"
+    return (f'<a class="signout" href="{html_mod.escape(url, quote=True)}">'
+            f'{html_mod.escape(label)}</a>')
+
+
+def fetch(path):
+    p = subprocess.run(["curl", "-sf", "--max-time", "30", BASE + path],
+                       capture_output=True, text=True)
+    if p.returncode != 0:
+        raise RuntimeError(f"fetch failed for {path} — is the dashboard running at {BASE}? (npm start)")
+    return p.stdout
+
+
+def main():
+    # Build into a staging directory and swap only once every page has been
+    # fetched. Emptying site/ first meant that a dashboard which happened to
+    # be down at 07:00 left an empty directory for the afterRun rsync hook to
+    # publish over the live mirror.
+    out = SITE.with_name(SITE.name + ".new")
+    if out.exists():
+        shutil.rmtree(out)
+    out.mkdir(parents=True)
+    try:
+
+        stamp = datetime.now(timezone.utc).isoformat(timespec="minutes")
+        staleness = (
+            '<script>(function(){var g=new Date("' + stamp + '");'
+            'var h=(Date.now()-g.getTime())/36e5;'
+            'if(h>36){var b=document.createElement("div");b.className="stale-banner";'
+            'b.textContent="⚠ This mirror is "+Math.round(h)+"h old — the daily run has not published since '
+            + stamp + ' UTC. Check the machine that runs it.";'
+            'document.body.prepend(b);}})();</script>'
+        )
+        signout = sign_out_link()
+        rs = routes()
+        for route in rs:
+            html = fetch(route)
+            html = html.replace("<head>", '<head><meta name="robots" content="noindex, nofollow">', 1)
+            if signout:
+                html = EXPORT_SLOT.sub(signout, html, count=1)
+            html = html.replace("</body>", staleness + "</body>", 1)
+            dest = out / "index.html" if route == "/" else out / route.lstrip("/") / "index.html"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(html)
+
+        (out / "styles.css").write_text(fetch("/styles.css"))
+        (out / "favicon.svg").write_text(fetch("/favicon.svg"))
+        (out / "robots.txt").write_text("User-agent: *\nDisallow: /\n")
+    except BaseException:
+        # Never leave a half-built staging directory behind; the next
+        # run would otherwise start from someone else's leftovers.
+        shutil.rmtree(out, ignore_errors=True)
+        raise
+
+    if SITE.exists():
+        shutil.rmtree(SITE)
+    out.rename(SITE)
+    print(f"exported {len(rs)} pages to {SITE}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/ops/hn_digest.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Daily Hacker News comment-opportunity digest (modules.hackerNews).
+
+Finds active HN threads in your expertise areas via the public Algolia API
+and writes the best candidates, each with a short briefing, to
+data/hn-digest.json for the dashboard. The point is to make GENUINE
+participation fast — the comments themselves are yours. This script never
+generates comment text, and the briefing prompt forbids it.
+
+Config: modules.hackerNews.topics = [[query, why-you], ...],
+modules.hackerNews.user = your HN username (marks threads you already joined),
+participation.expertise = the persona the briefing is written for.
+Briefings need modules.llm; without it, picks are listed unbriefed.
+"""
+
+import json
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from urllib.parse import quote
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ingest"))
+import seo_config  # noqa: E402
+import llm  # noqa: E402
+from http_util import fetch_text, get_json  # noqa: E402
+
+CUTOFF_HOURS = 48
+MIN_COMMENTS = 0    # early threads are prime commenting real estate
+MAX_COMMENTS = 120  # not already saturated
+MAX_PICKS = 5
+
+
+def search(query):
+    since = int((datetime.now(timezone.utc) - timedelta(hours=CUTOFF_HOURS)).timestamp())
+    filters = quote(f"created_at_i>{since},num_comments>={MIN_COMMENTS},num_comments<{MAX_COMMENTS}")
+    url = ("https://hn.algolia.com/api/v1/search_by_date?tags=story"
+           f"&numericFilters={filters}&hitsPerPage=5&query={quote(query)}")
+    try:
+        return get_json(url, label="hn search").get("hits", [])
+    except RuntimeError:
+        return []
+
+
+def article_text(url, cap=4000):
+    if not url:
+        return ""
+    _, body = fetch_text(url)
+    t = re.sub(r"<(script|style|noscript)[^>]*>.*?</\1>", " ", body, flags=re.S | re.I)
+    t = re.sub(r"<[^>]+>", " ", t)
+    return re.sub(r"\s+", " ", t).strip()[:cap]
+
+
+def top_comments(object_id, cap=5):
+    try:
+        kids = get_json(f"https://hn.algolia.com/api/v1/items/{object_id}", label="hn item").get("children", [])[:cap]
+    except RuntimeError:
+        return ""
+    out = []
+    for k in kids:
+        txt = re.sub(r"<[^>]+>", " ", k.get("text") or "")
+        if txt.strip():
+            out.append(re.sub(r"\s+", " ", txt).strip()[:400])
+    return "\n".join(out)
+
+
+def briefing(pick, expertise):
+    prompt = (
+        f"About the reader (first-hand expertise): {expertise}\n\n"
+        f"HN story: {pick['title']}\n"
+        f"Article excerpt:\n{article_text(pick.get('story_url')) or '(no article text — likely a Show HN app or paywalled)'}\n\n"
+        f"Top comments so far:\n{top_comments(pick.get('id')) or '(none yet)'}\n\n"
+        "Write a briefing for the reader in EXACTLY this format, one line each:\n"
+        "GIST: <one sentence — what the article/story actually says>\n"
+        "THREAD: <one sentence — what commenters are focusing on or debating>\n"
+        "ANGLE: <1-2 sentences — where the reader's genuine first-hand experience connects, and any of THEIR OWN facts worth citing. If their expertise does not genuinely connect, say 'weak fit — skip unless personally interested.'>\n"
+        "Do NOT write any comment text or suggested wording — briefing only."
+    )
+    out = llm.infer(prompt, fast=True) or ""
+    return out if "GIST:" in out else ""
+
+
+def _fb(path):
+    try:
+        return get_json(f"https://hacker-news.firebaseio.com/v0/{path}.json", label="hn firebase") or {}
+    except RuntimeError:
+        return {}
+
+
+def my_activity(user, recent=30):
+    """Story ids the user has commented on + profile stats. Uses the Firebase
+    API rather than Algolia's author search, which can lag days behind for
+    young accounts. Comments carry only a parent id, so walk up to the story."""
+    if not user:
+        return set(), None
+    profile = _fb(f"user/{user}")
+    submitted = profile.get("submitted", []) or []
+    story_ids, comment_count = set(), 0
+    for item_id in submitted[:recent]:
+        it = _fb(f"item/{item_id}")
+        if it.get("type") != "comment" or it.get("dead"):
+            continue
+        comment_count += 1
+        cur = it
+        for _ in range(8):
+            parent = cur.get("parent")
+            if parent is None:
+                break
+            cur = _fb(f"item/{parent}")
+            if cur.get("type") == "story":
+                story_ids.add(str(parent))
+                break
+    return story_ids, {"user": user, "karma": profile.get("karma"),
+                       "created": profile.get("created"), "comments": comment_count}
+
+
+def main():
+    m = seo_config.module("hackerNews")
+    if not m.get("enabled"):
+        print("hackerNews module disabled (modules.hackerNews.enabled) — skipping")
+        return 0
+    topics = [t for t in (m.get("topics") or []) if isinstance(t, list) and t and t[0]]
+    if not topics:
+        print("hackerNews: no topics configured — add [query, why] pairs in Settings")
+        return 0
+    expertise = (seo_config.load()["participation"] or {}).get("expertise", "").strip()
+
+    picks, seen = [], set()
+    for query, *rest in topics:
+        why = rest[0] if rest else ""
+        for h in search(query):
+            oid = h.get("objectID")
+            if oid in seen:
+                continue
+            seen.add(oid)
+            picks.append({
+                "id": oid,
+                "title": h.get("title", ""),
+                "url": f"https://news.ycombinator.com/item?id={oid}",
+                "story_url": h.get("url") or "",
+                "comments": h.get("num_comments", 0),
+                "points": h.get("points", 0),
+                "why": why,
+            })
+    picks.sort(key=lambda p: -((p["points"] or 0) + 2 * (p["comments"] or 0)))
+    picks = picks[:MAX_PICKS]
+
+    commented_ids, stats = my_activity((m.get("user") or "").strip())
+    can_brief = llm.available(fast=True) and bool(expertise)
+    if picks and not can_brief:
+        print("briefings skipped: " + ("participation.expertise is empty" if not expertise
+                                       else "llm module off"))
+    for pick in picks:
+        pick["commented"] = str(pick.get("id")) in commented_ids
+        pick["briefing"] = briefing(pick, expertise) if (can_brief and not pick["commented"]) else ""
+
+    seo_config.DATA.mkdir(parents=True, exist_ok=True)
+    (seo_config.DATA / "hn-digest.json").write_text(json.dumps(
+        {"generated": datetime.now(timezone.utc).isoformat(timespec="minutes"),
+         "stats": stats, "picks": picks}, indent=1))
+    for p in picks:
+        print(f"- {p['title']} ({p['comments']}c/{p['points']}p) {p['url']}  [{p['why']}]")
+    if not picks:
+        print("no matching active threads today")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/ops/indexnow.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""IndexNow: tell Bing, Copilot, Yandex and friends about changed URLs (modules.indexNow).
+
+  python3 ops/indexnow.py init                 # create the key file, print where each site must serve it
+  python3 ops/indexnow.py ping URL [URL ...]   # submit changed URLs (grouped by host)
+
+The key is public by design: every site serves it at https://<host>/<key>.txt
+and that is how IndexNow verifies you own the host. Free, instant, and it
+does nothing for Google (Google's fast lane is Request Indexing in the
+Search Console UI).
+"""
+
+import json
+import secrets
+import subprocess
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ingest"))
+import seo_config  # noqa: E402
+
+ENDPOINT = "https://api.indexnow.org/indexnow"
+
+
+def key_file() -> Path:
+    m = seo_config.module("indexNow")
+    p = m.get("keyFile") or "indexnow.key"
+    path = Path(p)
+    return path if path.is_absolute() else seo_config.INSTANCE / path
+
+
+def cmd_init() -> int:
+    kf = key_file()
+    if kf.exists():
+        key = kf.read_text().strip()
+        print(f"key file already exists: {kf}")
+    else:
+        key = secrets.token_hex(16)
+        kf.parent.mkdir(parents=True, exist_ok=True)
+        kf.write_text(key + "\n")
+        print(f"wrote {kf}")
+    print(f"\nkey: {key}\n\nServe this key as plain text at, for every site:")
+    for s in seo_config.sites():
+        print(f"  https://{s['gscHost']}/{key}.txt   (content: {key})")
+    print("\nThen: python3 ops/indexnow.py ping https://example.com/changed-page")
+    return 0
+
+
+def cmd_ping(urls: list[str]) -> int:
+    kf = key_file()
+    if not kf.exists():
+        print(f"no key file at {kf} — run: python3 ops/indexnow.py init")
+        return 1
+    key = kf.read_text().strip()
+    by_host: dict[str, list[str]] = {}
+    for u in urls:
+        host = urlsplit(u).netloc
+        if not host:
+            print(f"skipping non-URL argument: {u}")
+            continue
+        by_host.setdefault(host, []).append(u)
+    if not by_host:
+        print("nothing to ping")
+        return 1
+    rc = 0
+    for host, group in by_host.items():
+        body = json.dumps({
+            "host": host, "key": key,
+            "keyLocation": f"https://{host}/{key}.txt",
+            "urlList": group,
+        })
+        # IndexNow answers 200/202 with an EMPTY body, so the status code is
+        # the whole answer — plain curl rather than the JSON helper.
+        p = subprocess.run(["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+                            "--max-time", "30", "-X", "POST",
+                            "-H", "Content-Type: application/json; charset=utf-8",
+                            "-d", body, ENDPOINT], capture_output=True, text=True)
+        code = p.stdout.strip()
+        if code in ("200", "202"):
+            print(f"{host}: {code} — submitted {len(group)} URL(s)")
+        else:
+            rc = 1
+            hint = {"400": "bad request", "403": "key not found at keyLocation — is it served?",
+                    "422": "URLs don't belong to this host", "429": "too many requests"}.get(code, "")
+            print(f"{host}: HTTP {code or 'no response'} {hint}")
+    return rc
+
+
+def main() -> int:
+    if not seo_config.enabled("indexNow"):
+        print("indexNow module disabled — enable modules.indexNow in Settings or the config file")
+        return 1
+    args = sys.argv[1:]
+    if not args or args[0] not in ("init", "ping"):
+        print(__doc__)
+        return 2
+    if args[0] == "init":
+        return cmd_init()
+    if len(args) < 2:
+        print("ping needs at least one URL")
+        return 2
+    return cmd_ping(args[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())