n-seo 0.1.0

package/ops/install-launchd.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Install (or remove) the two macOS LaunchAgents for n-seo:
+#   n-seo.dashboard  — the dashboard, kept alive, starts at login
+#   n-seo.daily      — ops/daily.py at 07:00 local (fires on wake if missed)
+#
+# Usage:  ops/install-launchd.sh            install / reinstall
+#         ops/install-launchd.sh --uninstall
+#
+# Idempotent: re-running replaces the plists and reloads the jobs.
+set -euo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEMPLATES="$REPO/ops/templates"
+AGENTS="$HOME/Library/LaunchAgents"
+LABELS=(n-seo.dashboard n-seo.daily)
+DOMAIN="gui/$(id -u)"
+
+if [[ "$(uname)" != "Darwin" ]]; then
+  echo "This installer is for macOS launchd. On Linux see docs/SCHEDULING.md (cron / systemd)." >&2
+  exit 1
+fi
+
+unload() {
+  local label="$1" plist="$AGENTS/$1.plist"
+  if launchctl print "$DOMAIN/$label" >/dev/null 2>&1; then
+    launchctl bootout "$DOMAIN/$label" 2>/dev/null \
+      || launchctl unload -w "$plist" 2>/dev/null || true
+    echo "unloaded $label"
+  fi
+}
+
+if [[ "${1:-}" == "--uninstall" ]]; then
+  for label in "${LABELS[@]}"; do
+    unload "$label"
+    if [[ -f "$AGENTS/$label.plist" ]]; then
+      rm -f "$AGENTS/$label.plist"
+      echo "removed $AGENTS/$label.plist"
+    fi
+  done
+  echo "done — n-seo LaunchAgents removed"
+  exit 0
+fi
+
+NODE="$(command -v node || true)"
+if [[ -z "$NODE" ]]; then
+  echo "node not found on PATH — install Node 20+ first" >&2
+  exit 1
+fi
+NODE_BIN="$(dirname "$NODE")"
+
+mkdir -p "$AGENTS" "$REPO/data"
+
+for label in "${LABELS[@]}"; do
+  src="$TEMPLATES/$label.plist"
+  dst="$AGENTS/$label.plist"
+  [[ -f "$src" ]] || { echo "missing template $src" >&2; exit 1; }
+  unload "$label"
+  sed -e "s|__REPO__|$REPO|g" \
+      -e "s|__NODE_BIN__|$NODE_BIN|g" \
+      -e "s|__HOME__|$HOME|g" "$src" > "$dst"
+  plutil -lint "$dst" >/dev/null
+  if launchctl bootstrap "$DOMAIN" "$dst" 2>/dev/null; then
+    echo "loaded $label (bootstrap)"
+  else
+    launchctl load -w "$dst"
+    echo "loaded $label (load -w)"
+  fi
+done
+
+echo
+echo "installed:"
+echo "  $AGENTS/n-seo.dashboard.plist  → dashboard, log: $REPO/data/dashboard.log"
+echo "  $AGENTS/n-seo.daily.plist      → ops/daily.py at 07:00, log: $REPO/data/daily-launchd.log"
+echo
+echo "restart the dashboard after code changes:"
+echo "  launchctl kickstart -k $DOMAIN/n-seo.dashboard"

package/ops/llm.py

@@ -0,0 +1,139 @@
+"""Optional LLM inference, behind modules.llm. Two ways to reach a model.
+
+  command (default)
+      Any CLI that reads a prompt on stdin and prints a reply on stdout —
+      `claude -p --model claude-sonnet-5`, `llm -m gpt-4o`,
+      `ollama run llama3`, or a shell script.
+
+  http
+      An HTTP endpoint, for machines with no CLI signed in — which is every
+      container and every server you did not log into by hand. Configure:
+
+        "llm": {
+          "enabled": true,
+          "http": {
+            "provider": "anthropic",              // or "openai"
+            "model": "claude-sonnet-5",
+            "fastModel": "claude-haiku-4-5-20251001",
+            "apiKeyEnv": "ANTHROPIC_API_KEY",     // read from the env or .env
+            "baseUrl": ""                          // optional, for a gateway
+          }
+        }
+
+      `provider: "openai"` speaks the OpenAI chat-completions shape, so it
+      also covers the many gateways and local servers that emulate it.
+
+`http` wins when it is configured and its key resolves; otherwise the CLI
+path runs. Nothing that comes back is applied automatically: callers turn
+replies into briefings or proposals a human accepts or ignores.
+"""
+import json
+import shlex
+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
+from http_util import curl_json  # noqa: E402
+
+ANTHROPIC_VERSION = "2023-06-01"
+MAX_TOKENS = 4096
+
+
+def _enabled() -> dict | None:
+    m = seo_config.module("llm")
+    return m if m.get("enabled") else None
+
+
+def http_config(fast: bool = False) -> dict | None:
+    """The resolved HTTP config, or None when it is absent or has no key."""
+    m = _enabled()
+    if not m:
+        return None
+    h = m.get("http")
+    if not isinstance(h, dict):
+        return None
+    provider = str(h.get("provider") or "").lower()
+    model = (h.get("fastModel") if fast else None) or h.get("model")
+    if provider not in ("anthropic", "openai") or not model:
+        return None
+    key = seo_config.env(str(h.get("apiKeyEnv") or ""))
+    if not key:
+        return None
+    return {"provider": provider, "model": str(model),
+            "baseUrl": str(h.get("baseUrl") or "").rstrip("/"), "key": key}
+
+
+def command(fast: bool = False) -> list[str] | None:
+    m = _enabled()
+    if not m:
+        return None
+    cmd = (m.get("fastCommand") if fast else None) or m.get("command") or ""
+    parts = shlex.split(str(cmd))
+    if not parts or not shutil.which(parts[0]):
+        return None
+    return parts
+
+
+def available(fast: bool = False) -> bool:
+    return http_config(fast) is not None or command(fast) is not None
+
+
+def _http_infer(cfg: dict, prompt: str, fast: bool) -> str | None:
+    timeout = 120 if fast else 300
+    if cfg["provider"] == "anthropic":
+        url = (cfg["baseUrl"] or "https://api.anthropic.com") + "/v1/messages"
+        args = ["-X", "POST",
+                "-H", f"x-api-key: {cfg['key']}",
+                "-H", f"anthropic-version: {ANTHROPIC_VERSION}",
+                "-H", "Content-Type: application/json",
+                "-d", json.dumps({"model": cfg["model"], "max_tokens": MAX_TOKENS,
+                                  "messages": [{"role": "user", "content": prompt}]}),
+                url]
+    else:
+        url = (cfg["baseUrl"] or "https://api.openai.com") + "/v1/chat/completions"
+        args = ["-X", "POST",
+                "-H", f"Authorization: Bearer {cfg['key']}",
+                "-H", "Content-Type: application/json",
+                "-d", json.dumps({"model": cfg["model"],
+                                  "messages": [{"role": "user", "content": prompt}]}),
+                url]
+    try:
+        resp = curl_json(args, timeout=timeout, attempts=2, label=f"llm {cfg['provider']}")
+    except (RuntimeError, OSError) as exc:
+        print(f"  llm: {exc}", file=sys.stderr)
+        return None
+    try:
+        if cfg["provider"] == "anthropic":
+            out = "".join(b.get("text", "") for b in resp["content"] if b.get("type") == "text")
+        else:
+            out = resp["choices"][0]["message"]["content"]
+    except (KeyError, IndexError, TypeError):
+        detail = resp.get("error") if isinstance(resp, dict) else resp
+        print(f"  llm: unexpected response: {json.dumps(detail)[:200]}", file=sys.stderr)
+        return None
+    return (out or "").strip() or None
+
+
+def infer(prompt: str, fast: bool = False) -> str | None:
+    """A reply, or None when the module is off, nothing is reachable, or the
+    call fails or times out. Never raises: every caller degrades instead."""
+    http = http_config(fast)
+    if http:
+        return _http_infer(http, prompt, fast)
+    parts = command(fast)
+    if not parts:
+        return None
+    try:
+        p = subprocess.run(parts, input=prompt, capture_output=True, text=True,
+                           timeout=120 if fast else 300)
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        print(f"  llm: {exc}", file=sys.stderr)
+        return None
+    if p.returncode != 0:
+        print(f"  llm: exit {p.returncode}: {p.stderr.strip()[:200]}", file=sys.stderr)
+        return None
+    out = p.stdout.strip()
+    return out or None

package/ops/mcp-smoke-stdio.mjs

@@ -0,0 +1,61 @@
+// End-to-end check of the stdio MCP server against whatever is in data/.
+// Run from the repo root: `npm run mcp:smoke`
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["tsx", "src/mcp-stdio.ts"],
+  cwd: process.cwd(),
+  env: process.env,
+});
+const client = new Client({ name: "smoke-test", version: "1.0.0" });
+await client.connect(transport);
+
+const { tools } = await client.listTools();
+console.log(`TOOLS (${tools.length}):`);
+for (const t of tools) console.log(`  ${t.name.padEnd(24)} ${(t.description ?? "").slice(0, 62)}…`);
+
+const { resources } = await client.listResources();
+console.log(`\nRESOURCES (${resources.length}): ${resources.map((r) => r.uri).join(", ")}`);
+
+const call = async (name, args = {}) => {
+  const r = await client.callTool({ name, arguments: args });
+  const text = r.content?.[0]?.text ?? "";
+  return { isError: !!r.isError, text };
+};
+
+console.log("\n--- settings ---");
+let r = await call("settings");
+const settings = JSON.parse(r.text);
+console.log(`  name=${settings.name} sites=${settings.sites.map((s) => s.host).join(",") || "(none)"} modules on: ${Object.entries(settings.modules).filter(([, v]) => v).map(([k]) => k).join(", ") || "(none)"}`);
+const firstHost = settings.sites[0]?.host;
+
+console.log("\n--- list_actions {status:active, limit:3} ---");
+r = await call("list_actions", { status: "active", limit: 3 });
+const acts = JSON.parse(r.text);
+console.log(`  matched=${acts.matched} returned=${acts.returned}`);
+acts.actions.forEach((a) => console.log(`  #${a.rank} +${a.impact} ${a.effort} ${a.host} — ${a.title.slice(0, 54)}`));
+
+console.log("\n--- ops_status ---");
+r = await call("ops_status");
+const ops = JSON.parse(r.text);
+console.log(`  lastRun=${ops.lastRun?.ts ?? "none"} failures="${ops.lastRun?.failures ?? ""}" probe=${ops.probe ? `${ops.probe.healthy}/${ops.probe.total} healthy` : "none"}`);
+(ops.probe?.sites ?? []).filter((s) => s.findings.length).forEach((s) => console.log(`  ${s.host}: ${s.findings.join("; ")}`));
+
+if (firstHost) {
+  console.log(`\n--- top_queries ${firstHost} 90d limit 3 ---`);
+  r = await call("top_queries", { host: firstHost, window: "90d", limit: 3 });
+  JSON.parse(r.text).queries.forEach((q) => console.log(`  "${q.query}" clicks=${q.clicks} imps=${q.impressions} pos=${(q.position ?? 0).toFixed(1)}`));
+}
+
+console.log("\n--- error path: unknown host ---");
+r = await call("site_report", { host: "nope.example.invalid" });
+console.log(`  isError=${r.isError} :: ${r.text.slice(0, 70)}`);
+
+console.log("\n--- conversions_status ---");
+r = await call("conversions_status");
+console.log("  " + r.text.replace(/\s+/g, " ").slice(0, 130));
+
+await client.close();
+console.log("\nstdio transport OK");

package/ops/opportunity_scan.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Automated opportunity discovery.
+
+Closes the loop that otherwise needs a human analysis session:
+  1. Refreshes the trend analysis (rising/falling queries, 84d windows).
+  2. SCRIPTED detection: rising queries not covered by any existing queue
+     action become candidates.
+  3. INFERENCE (optional, modules.llm): candidates + queue summary + watching
+     items go to the model, which returns strictly-JSON *proposals* (new
+     queue cards) and *verdicts* on watching items (succeeded / failed /
+     keep-watching).
+  4. Output -> data/opportunity-proposals.json, rendered on the Actions page
+     as PROPOSED cards. Nothing self-modifies the curated queue — you accept
+     proposals into config/backlog.json (the dashboard has a button).
+
+Inference runs when there are new candidates, and always on Mondays (weekly
+review of watching items). Without the LLM module it still writes candidates.
+"""
+
+import json
+import re
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "ingest"))
+import seo_config  # noqa: E402
+import llm  # noqa: E402
+
+ROOT = seo_config.ROOT
+DATA = seo_config.DATA
+RISE_MIN_IMPS = 30       # a riser must reach this many imps in the recent 84d
+RISE_MIN_RATIO = 2.5     # and have grown at least this much vs prior 84d
+
+
+def latest_trends():
+    files = sorted(DATA.glob("trends-*.json"))
+    return json.loads(files[-1].read_text()) if files else None
+
+
+def queue():
+    """The live queue from the dashboard (data-derived + curated). Falls back
+    to the curated backlog alone when the dashboard is not running."""
+    p = subprocess.run(["curl", "-sf", "--max-time", "30", seo_config.dashboard_base() + "/api/actions"],
+                       capture_output=True, text=True)
+    try:
+        acts = json.loads(p.stdout)
+        if isinstance(acts, list):
+            return acts
+    except json.JSONDecodeError:
+        pass
+    try:
+        return json.loads((seo_config.INSTANCE / "config" / "backlog.json").read_text()).get("actions", [])
+    except (OSError, json.JSONDecodeError):
+        return []
+
+
+def portfolio_description():
+    parts = []
+    for s in seo_config.sites():
+        desc = s["host"]
+        if s.get("label") and s["label"] != s["host"]:
+            desc += f" ({s['label']})"
+        parts.append(desc)
+    return ", ".join(parts)
+
+
+def _host_resolver(prop):
+    """query -> the configured host a riser belongs to.
+
+    A domain property can cover several configured sites, and a url-prefix
+    property's slug is not a host at all, so the trend file's key cannot be
+    used directly. One site on the property: that site. Several: the host of
+    the page with the most impressions for that query in the 90-day
+    query x page pull, falling back to the first configured site.
+    """
+    owners = [s for s in seo_config.sites() if s.get("gscProperty") == prop]
+    if not owners:
+        return lambda q: seo_config.gsc_slug(prop)  # a bare host is the best we have
+    if len(owners) == 1:
+        return lambda q: owners[0]["host"]
+    by_gsc_host = {s["gscHost"]: s["host"] for s in owners}
+    best = {}
+    qp = seo_config.DATA / "gsc" / seo_config.gsc_data_slug(prop) / "query_page_90d.json"
+    try:
+        for r in json.loads(qp.read_text()).get("rows", []):
+            q, page = r["keys"][0], r["keys"][1]
+            h = page.split("/")[2] if page.count("/") >= 2 else ""
+            if h in by_gsc_host and r["impressions"] > best.get(q, (0, ""))[0]:
+                best[q] = (r["impressions"], by_gsc_host[h])
+    except (OSError, json.JSONDecodeError, KeyError, IndexError):
+        pass
+    return lambda q: best.get(q, (0, owners[0]["host"]))[1]
+
+
+def main():
+    # 1. refresh trends (also keeps the /insights tables current)
+    if seo_config.gsc_properties() or seo_config.ga4_properties():
+        r = subprocess.run([sys.executable, str(ROOT / "ingest" / "analyze_trends.py")],
+                           capture_output=True, text=True)
+        if r.returncode != 0:
+            last = (r.stderr or r.stdout).strip().splitlines()
+            print("trend refresh failed:", last[-1][:200] if last else "(no output)",
+                  "— using the latest trends file on disk")
+
+    trends = latest_trends()
+    if not trends:
+        print("no trends file — scan aborted (run ingest/analyze_trends.py once data exists)")
+        return 1
+    actions = queue()
+
+    queue_text = " || ".join(
+        f"{a.get('title','')} :: {a.get('why','')} :: {' '.join(a.get('spec', []))}" for a in actions
+    ).lower()
+    active = [a for a in actions if not a.get("watching")]
+    watching = [a for a in actions if a.get("watching")]
+
+    # 2. scripted candidate detection: uncovered risers
+    candidates = []
+    for site, d in trends.get("sites", {}).items():
+        host_for = _host_resolver(site)
+        for m in d.get("rising", []):
+            if m["recent_imps"] < RISE_MIN_IMPS:
+                continue
+            if m["prior_imps"] and m["recent_imps"] / max(1, m["prior_imps"]) < RISE_MIN_RATIO:
+                continue
+            # Substring matching dropped genuine risers: a one-word query
+            # ("pricing", "canvas") appears inside some unrelated card's prose
+            # and the riser is written off as already covered.
+            if re.search(rf"\b{re.escape(m['query'].lower())}\b", queue_text):
+                continue  # already covered by an action
+            candidates.append({"host": host_for(m["query"]), **m})
+    candidates.sort(key=lambda c: -c["recent_imps"])
+    candidates = candidates[:12]
+
+    run_inference = (bool(candidates) or date.today().weekday() == 0) and llm.available()
+    out = {"generated": date.today().isoformat(), "candidates": candidates,
+           "proposals": [], "verdicts": [], "inference_ran": False}
+
+    if run_inference:
+        prompt = (
+            "You are the SEO strategist for a small portfolio of websites: "
+            + portfolio_description() + ". "
+            "Growth levers available: new/updated pages, titles/meta, internal links, llms.txt/AI-crawler surface, "
+            "distribution (communities, newsletters, directories). No paid ads.\n\n"
+            "UNCOVERED RISING QUERIES (84d vs prior 84d, none matched by existing queue actions):\n"
+            + json.dumps(candidates, indent=1)
+            + "\n\nEXISTING ACTIVE QUEUE (titles only — do NOT duplicate):\n"
+            + json.dumps([a.get("title") for a in active], indent=1)
+            + "\n\nWATCHING ITEMS (shipped work + status note; judge each against its note):\n"
+            + json.dumps([{"title": a.get("title"), "note": a.get("watching"), "why": a.get("why", "")} for a in watching], indent=1)
+            + "\n\nReturn STRICT JSON only, no prose, matching exactly:\n"
+            '{"proposals":[{"host":"...","title":"...","kind":"...","why":"... (cite the query numbers)",'
+            '"how":"...","spec":["..."],"impact":<int clicks/mo estimate>,"effort":"S|M|L","tag":"content|striking|metadata|distribution|hygiene"}],'
+            '"verdicts":[{"title":"<exact watching title>","verdict":"succeeded|failed|keep-watching","evidence":"..."}]}\n'
+            "Rules: 0-4 proposals, only where the rising-query evidence genuinely supports a concrete move; "
+            "each proposal must name real pages/URLs in spec; impact is an ordering estimate, not a forecast — be conservative; "
+            "verdicts only where the data above lets you judge — otherwise keep-watching with a one-line reason."
+        )
+        raw = llm.infer(prompt) or ""
+        m = re.search(r"\{.*\}", raw, re.S)
+        if m:
+            try:
+                parsed = json.loads(m.group(0))
+                out["proposals"] = [x for x in parsed.get("proposals", [])
+                                    if x.get("title") and x.get("host") and x.get("spec")]
+                out["verdicts"] = parsed.get("verdicts", [])
+                out["inference_ran"] = True
+            except json.JSONDecodeError:
+                print("inference returned unparseable JSON — kept candidates only")
+        else:
+            print("inference produced no JSON — kept candidates only")
+    elif candidates and not llm.available():
+        print("llm module off — candidates recorded without proposals")
+
+    DATA.mkdir(parents=True, exist_ok=True)
+    (DATA / "opportunity-proposals.json").write_text(json.dumps(out, indent=1))
+    print(f"candidates: {len(candidates)} | proposals: {len(out['proposals'])} | "
+          f"verdicts: {len(out['verdicts'])} | inference: {out['inference_ran']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/ops/publish.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Publish the exported mirror somewhere (modules.publish).
+
+`ops/export_static.py` builds a read-only copy of the dashboard into
+`site/`. Getting that copy to wherever people read it — a bucket, an object
+store, a box over ssh — is the other half, and it used to mean writing an
+`afterRun` hook by hand. This makes it a normal pipeline step, so it is
+logged, retried once and recorded in `last-run.json` like everything else.
+
+  python3 ops/publish.py              # publish site/ to modules.publish.destination
+
+Targets:
+
+  gcs      gcloud storage rsync site <dest> --recursive
+  s3       aws s3 sync site <dest>
+  rsync    rsync -a site/ <dest>
+  command  run modules.publish.command — the escape hatch for anything else
+
+`delete` adds each tool's "remove what is no longer here" flag, which is what
+makes the mirror match the export rather than accumulate stale pages. Set
+`dryRun` to print the command without running it: that is how you rehearse a
+cutover against a bucket that is already serving something.
+
+`env` is merged into the child's environment only — a deployment that keeps
+its cloud credentials in an isolated config directory points at it there,
+without exporting it for the whole daily run. Values are never printed.
+"""
+
+import os
+import shlex
+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
+
+TARGETS = ("gcs", "s3", "rsync", "command")
+
+# target -> the binary that must be on PATH ("command" runs a shell string)
+BINARY = {"gcs": "gcloud", "s3": "aws", "rsync": "rsync"}
+
+DEST_EXAMPLE = {
+    "gcs": "gs://your-bucket",
+    "s3": "s3://your-bucket",
+    "rsync": "user@host:/srv/n-seo-mirror",
+}
+
+
+def site_dir() -> Path:
+    return seo_config.INSTANCE / "site"
+
+
+def build_command(mod: dict, site: Path):
+    """(command, shell) for the configured target.
+
+    `command` is an argv list for the three built-in targets and a shell
+    string for `command`; `shell` says which. Raises ValueError with a
+    message meant for the operator, not a stack trace.
+    """
+    target = (mod.get("target") or "").strip()
+    if target not in TARGETS:
+        raise ValueError(
+            f"unknown publish target {target!r} — use one of: {', '.join(TARGETS)}")
+
+    if target == "command":
+        cmd = (mod.get("command") or "").strip()
+        if not cmd:
+            raise ValueError(
+                "modules.publish.command is empty — target 'command' needs the "
+                "shell command that publishes site/")
+        return cmd, True
+
+    dest = (mod.get("destination") or "").strip()
+    if not dest:
+        raise ValueError(
+            f"modules.publish.destination is empty — set it to something like "
+            f"{DEST_EXAMPLE[target]} for target {target!r}")
+
+    delete = bool(mod.get("delete"))
+    if target == "gcs":
+        argv = ["gcloud", "storage", "rsync", str(site), dest, "--recursive"]
+        if delete:
+            argv.append("--delete-unmatched-destination-objects")
+    elif target == "s3":
+        argv = ["aws", "s3", "sync", str(site), dest]
+        if delete:
+            argv.append("--delete")
+    else:  # rsync — the trailing slash copies the contents, not the directory
+        argv = ["rsync", "-a", str(site) + "/", dest]
+        if delete:
+            argv.append("--delete")
+    return argv, False
+
+
+def child_env(mod: dict) -> dict:
+    """The daily run's environment plus modules.publish.env.
+
+    `~` and $VARS in the values are expanded so a credentials path can be
+    written the way a person would type it.
+    """
+    env = dict(os.environ)
+    for k, v in (mod.get("env") or {}).items():
+        if isinstance(k, str) and k:
+            env[k] = os.path.expanduser(os.path.expandvars(str(v)))
+    return env
+
+
+def main() -> int:
+    if not seo_config.enabled("publish"):
+        print("modules.publish is off — nothing to publish")
+        return 0
+    mod = seo_config.module("publish")
+
+    site = site_dir()
+    try:
+        cmd, shell = build_command(mod, site)
+    except ValueError as exc:
+        print(f"publish: {exc}", file=sys.stderr)
+        return 1
+
+    if not site.is_dir():
+        print(f"publish: nothing to publish — {site} does not exist. Enable "
+              f"modules.staticExport so the daily run builds it first.",
+              file=sys.stderr)
+        return 1
+
+    target = mod["target"]
+    binary = BINARY.get(target)
+    if binary and shutil.which(binary) is None:
+        print(f"publish: {binary!r} is not on PATH — target {target!r} needs it "
+              f"(install it, or use target 'command')", file=sys.stderr)
+        return 1
+
+    printable = cmd if shell else " ".join(shlex.quote(a) for a in cmd)
+    # Key names only: a publish env is where credentials paths and tokens live.
+    env_keys = sorted(k for k in (mod.get("env") or {}) if isinstance(k, str) and k)
+    if env_keys:
+        print(f"publish: env {', '.join(env_keys)}")
+
+    if mod.get("dryRun"):
+        print(f"publish: DRY RUN — would run:\n  {printable}\n"
+              f"publish: set modules.publish.dryRun to false to publish for real")
+        return 0
+
+    print(f"publish: {printable}")
+    p = subprocess.run(cmd, shell=shell, cwd=seo_config.INSTANCE, env=child_env(mod))
+    if p.returncode != 0:
+        print(f"publish: FAILED (exit {p.returncode}) — {target} → "
+              f"{mod.get('destination') or 'command'}", file=sys.stderr)
+        return 1
+    print(f"publish: {site.name}/ → {mod.get('destination') or 'command'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())