n-seo 0.1.0 → 0.2.0

package/ops/opportunity_scan.py

@@ -36,7 +36,7 @@ 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
+    return json.loads(files[-1].read_text(encoding="utf-8")) if files else None
 
 
 def queue():
@@ -51,7 +51,7 @@ def queue():
     except json.JSONDecodeError:
         pass
     try:
-        return json.loads((seo_config.INSTANCE / "config" / "backlog.json").read_text()).get("actions", [])
+        return json.loads((seo_config.INSTANCE / "config" / "backlog.json").read_text(encoding="utf-8")).get("actions", [])
     except (OSError, json.JSONDecodeError):
         return []
 
@@ -84,7 +84,7 @@ def _host_resolver(prop):
     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", []):
+        for r in json.loads(qp.read_text(encoding="utf-8")).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]:
@@ -175,7 +175,7 @@ def main():
         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))
+    (DATA / "opportunity-proposals.json").write_text(json.dumps(out, indent=1), encoding="utf-8")
     print(f"candidates: {len(candidates)} | proposals: {len(out['proposals'])} | "
           f"verdicts: {len(out['verdicts'])} | inference: {out['inference_ran']}")
     return 0

package/ops/py.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/* Run a Python script with whichever interpreter this machine actually has.
+ *
+ * The npm scripts used to hardcode `python3`, which does not exist on
+ * Windows: Python installs there as `python`, or only behind the `py`
+ * launcher. Worse, Windows ships an App Execution Alias at `python3.exe`
+ * that opens the Microsoft Store instead of running anything, so a hardcoded
+ * `python3` fails in a way that looks like Python is missing when it is not.
+ * Probing for one that answers `--version` is the only reliable answer.
+ *
+ *   node ops/py.mjs ops/doctor.py --offline
+ *
+ * $PYTHON overrides, which is also how the n-seo CLI behaves.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const CANDIDATES = process.platform === "win32"
+  ? ["python", "python3", "py"]
+  : ["python3", "python"];
+
+export function pythonBin() {
+  if (process.env.PYTHON) return process.env.PYTHON;
+  for (const c of CANDIDATES) {
+    const probe = spawnSync(c, ["--version"], { stdio: "ignore" });
+    if (!probe.error && probe.status === 0) return c;
+  }
+  return CANDIDATES[0]; // let the real command fail with a useful message
+}
+
+// Only act as a launcher when invoked directly, not when imported.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const child = spawn(pythonBin(), process.argv.slice(2), { stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(`could not start ${pythonBin()}: ${err.message}`);
+    console.error("install Python 3.10+, or set $PYTHON to its path");
+    process.exit(127);
+  });
+  child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 1));
+}

package/ops/reddit_digest.py

@@ -151,7 +151,7 @@ def main():
     seo_config.DATA.mkdir(parents=True, exist_ok=True)
     (seo_config.DATA / "reddit-digest.json").write_text(json.dumps(
         {"generated": datetime.now(timezone.utc).isoformat(timespec="minutes"),
-         "user": user or None, "auth": bool(oauth_token()), "picks": picks}, indent=1))
+         "user": user or None, "auth": bool(oauth_token()), "picks": picks}, indent=1), encoding="utf-8")
     for p in picks:
         print(f"- r/{p['sub']}: {p['title']} ({p['comments']}c/{p['score']}pts, {p['age_days']}d) {p['url']}")
     if not picks:

package/ops/templates/n-seo-daily-task.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-16"?>
+<!--
+  n-seo daily run at 07:00 local, for Windows Task Scheduler.
+
+  Register it (from an elevated or normal prompt, your choice — this is a
+  per-user task):
+
+    schtasks /create /tn "n-seo daily" /xml ops\templates\n-seo-daily-task.xml
+
+  Before you do, replace the two placeholders below:
+    __NSEO__     the n-seo command, e.g. C:\Users\you\AppData\Roaming\npm\n-seo.cmd
+                 (find it with:  where n-seo)
+    __INSTANCE__ your instance directory, e.g. C:\Users\you\my-sites
+
+  StartWhenAvailable is the Windows equivalent of launchd's catch-up
+  behaviour: a machine that was asleep at 07:00 runs the job when it wakes,
+  rather than skipping the day the way cron does.
+-->
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>n-seo daily run: pulls Search Console and GA4, probes the sites, refreshes the queue.</Description>
+    <URI>\n-seo daily</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <StartBoundary>2026-01-01T07:00:00</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay>
+        <DaysInterval>1</DaysInterval>
+      </ScheduleByDay>
+    </CalendarTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>true</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT2H</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>__NSEO__</Command>
+      <Arguments>daily --instance "__INSTANCE__"</Arguments>
+      <WorkingDirectory>__INSTANCE__</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "n-seo",
-  "version": "0.1.0",
-  "description": "Local-first SEO / AEO / GEO control plane: pulls Search Console + GA4, probes your sites, and turns the data into a ranked action queue you can act on without an agency.",
+  "version": "0.2.0",
+  "description": "Agentic, local-first SEO / AEO / GEO control plane: pulls Search Console + GA4, probes your sites, and ranks the next moves. Your LLM writes the proposals; your coding agent works the queue over MCP.",
   "license": "MIT",
   "author": "En Dash Consulting (https://endash.us)",
-  "homepage": "https://en-dash-consulting.github.io/n-seo/",
+  "homepage": "https://n-seo.dev/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/en-dash-consulting/n-seo.git"
@@ -16,12 +16,19 @@
     "seo",
     "aeo",
     "geo",
+    "agent",
+    "ai-agent",
+    "agentic",
+    "llm",
+    "claude",
+    "claude-code",
+    "mcp",
+    "mcp-server",
     "search-console",
     "google-analytics",
     "ga4",
     "llms-txt",
     "ai-crawlers",
-    "mcp",
     "dashboard",
     "local-first",
     "cli"
@@ -53,13 +60,13 @@
     "typecheck": "tsc --noEmit",
     "mcp": "tsx src/mcp-stdio.ts",
     "mcp:smoke": "node ops/mcp-smoke-stdio.mjs",
-    "doctor": "python3 ops/doctor.py",
-    "demo": "python3 ops/demo_data.py",
-    "daily": "python3 ops/daily.py",
+    "doctor": "node ops/py.mjs ops/doctor.py",
+    "demo": "node ops/py.mjs ops/demo_data.py",
+    "daily": "node ops/py.mjs ops/daily.py",
     "test": "tsx --test tests/ts/*.test.ts",
-    "test:py": "python3 -m unittest discover -s tests/py -v",
+    "test:py": "node ops/py.mjs -m unittest discover -s tests/py -v",
     "check": "npm run typecheck && npm test && npm run test:py",
-    "export": "python3 ops/export_static.py",
+    "export": "node ops/py.mjs ops/export_static.py",
     "docker:build": "docker build -t n-seo:latest .",
     "docker:up": "docker compose -f docker/compose.yml up -d"
   },

package/probes/site_probe.py

@@ -173,7 +173,7 @@ def main():
     out_dir = seo_config.DATA / "probes"
     out_dir.mkdir(parents=True, exist_ok=True)
     out = out_dir / f"probe-{datetime.now(timezone.utc):%Y%m%d-%H%M%S}.json"
-    out.write_text(json.dumps(snapshot, indent=2))
+    out.write_text(json.dumps(snapshot, indent=2), encoding="utf-8")
 
     for s in snapshot["sites"]:
         h = s["homepage"]

package/src/actions.ts

@@ -118,7 +118,7 @@ function probeActions(site: SiteCfg): Action[] {
   const mk = (key: string, title: string, how: string): Action => ({
     id: `gen-hygiene-${slug(site.host)}-${key}`,
     host: site.host, title, kind: "Config change", why: "Live probe failing on this check", how,
-    spec: [how, `Verify with: python3 probes/site_probe.py after deploy.`],
+    spec: [how, `Verify with: n-seo daily --only probe after deploy.`],
     impact: 5, effort: "S", tag: "hygiene", source: "rule",
   });
   if (!p.robots.exists) out.push(mk("robots", "Add robots.txt", "Serve robots.txt with a Sitemap: pointer and explicit AI-crawler allowances."));

package/src/config.ts

@@ -80,7 +80,7 @@ export interface Hooks {
   beforeRun: string[];
   /** … after the last step (and after last-run.json is written) */
   afterRun: string[];
-  /** … after a named step, e.g. { "daily-diff": ["python3 my_sync.py"] } */
+  /** … after a named step, e.g. { "daily-diff": ["node my_sync.mjs"] } */
   afterStep: Record<string, string[]>;
 }
 

package/src/mcp.ts

@@ -273,7 +273,7 @@ export function createMcpServer(): McpServer {
     },
     async ({ host }) => {
       const audit = data.metadataAudit();
-      if (!audit) return fail("No metadata audit on disk yet — run python3 ingest/analyze_metadata.py.");
+      if (!audit) return fail("No metadata audit on disk yet — run `n-seo daily --only metadata-audit`.");
       if (!host) return json(audit);
       const findings = audit.sites[host];
       if (!findings) return fail(`No audit entry for "${host}". Known: ${Object.keys(audit.sites).join(", ")}`);
@@ -379,7 +379,7 @@ export function createMcpServer(): McpServer {
     },
     async () => {
       const scan = data.opportunityScan();
-      if (!scan) return fail("No opportunity scan on disk yet — run python3 ops/opportunity_scan.py.");
+      if (!scan) return fail("No opportunity scan on disk yet — run `n-seo daily --only opportunity-scan`.");
       return json(scan);
     }
   );

package/src/settings.tsx

@@ -105,7 +105,7 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
           <div class="s-title">Mode</div>
           <div class="mono">{cfg.google.auth}</div>
           <p class="sub">{cfg.google.auth === "service-account-key"
-            ? "A service-account JSON key, signed locally with openssl. No gcloud needed."
+            ? "A service-account JSON key. The JWT is signed locally with node's crypto module — no gcloud, no openssl, nothing to install."
             : cfg.google.auth === "metadata"
               ? "The runtime service account from the GCE / Cloud Run / GKE metadata server — no key file. It mints its own scoped tokens, which needs Token Creator on itself."
               : cfg.google.auth === "gcloud-impersonate"
@@ -122,7 +122,7 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
         <div class="s-card">
           <div class="s-title">Grant access to</div>
           <div class="mono">{sa.email ?? cfg.google.impersonate ?? (cfg.google.auth === "metadata" ? "the runtime service account" : "—")}</div>
-          <p class="sub">Add this email as a <b>Full</b> user on each Search Console property and a <b>Viewer</b> on each GA4 property. Then <code>python3 ops/doctor.py</code> confirms it can see them.</p>
+          <p class="sub">Add this email as a <b>Full</b> user on each Search Console property and a <b>Viewer</b> on each GA4 property. Then <code>n-seo doctor</code> confirms it can see them.</p>
         </div>
       </div>
 
@@ -254,7 +254,7 @@ export const SettingsPage: FC<{ saved?: boolean; error?: string }> = ({ saved, e
               <div class="mono">{lr.ts}</div>
               <p class="sub">{lr.failures.trim() ? <span class="chip bad">failed: {lr.failures}</span> : <span class="chip good">all steps OK</span>}</p>
             </>
-          ) : <p class="sub">never — run <code>python3 ops/daily.py</code></p>}
+          ) : <p class="sub">never — run <code>n-seo daily</code></p>}
         </div>
         <div class="s-card">
           <div class="s-title">Data freshness</div>

package/src/views.tsx

@@ -215,7 +215,7 @@ export const SplitQueue: FC<{ actions: Action[]; idPrefix: string }> = ({ action
       {active.length ? (
         <ActionQueue actions={active} showHost idPrefix={`${idPrefix}-a`} />
       ) : (
-        <p class="empty">Nothing active. Either the data has no findings yet (run <code>python3 ops/daily.py</code>) or the queue is clear — add strategic items in <code>config/backlog.json</code>.</p>
+        <p class="empty">Nothing active. Either the data has no findings yet (run <code>n-seo daily</code>) or the queue is clear — add strategic items in <code>config/backlog.json</code>.</p>
       )}
       {watching.length > 0 && (
         <>
@@ -526,7 +526,7 @@ export const SiteDetail: FC<{ site: SiteCfg; days?: number }> = ({ site, days =
       ) : (
         <p class="empty">
           {site.ga4Property || site.gscProperty
-            ? <>no time series yet — run <code>python3 ingest/pull_timeseries.py</code></>
+            ? <>no time series yet — run <code>n-seo daily --only timeseries</code></>
             : "no Search Console or GA4 property configured for this site"}
         </p>
       )}
@@ -614,11 +614,11 @@ export const SiteDetail: FC<{ site: SiteCfg; days?: number }> = ({ site, days =
 
 export const Probes: FC = () => {
   const probe = data.latestProbe();
-  if (!probe) return <><h1>Live-site probe</h1><p class="empty">No probe snapshots yet — run <code>python3 probes/site_probe.py</code></p></>;
+  if (!probe) return <><h1>Live-site probe</h1><p class="empty">No probe snapshots yet — run <code>n-seo daily --only probe</code></p></>;
   return (
     <>
       <h1>Live-site probe</h1>
-      <p class="sub">Snapshot {probe.probed_at} · no-auth checks of what crawlers actually see. Re-run any time: <code>python3 probes/site_probe.py</code></p>
+      <p class="sub">Snapshot {probe.probed_at} · no-auth checks of what crawlers actually see. Re-run any time: <code>n-seo daily --only probe</code></p>
       <div class="tbl-wrap"><table>
         <thead>
           <tr><th>Site</th><th>robots</th><th>AI crawlers</th><th>sitemap</th><th>llms.txt</th><th>404</th><th>JSON-LD</th><th>visible text</th><th>Title</th></tr>
@@ -704,7 +704,7 @@ export const IndexingPage: FC = () => {
       <>
         <h1>Indexing</h1>
         <p class="empty">
-          No index snapshot yet — enable the <b>Index coverage sweep</b> module and run <code>python3 ingest/pull_index_status.py</code>
+          No index snapshot yet — enable the <b>Index coverage sweep</b> module and run <code>n-seo daily --only index-status</code>
         </p>
       </>
     );
@@ -890,7 +890,7 @@ export const InsightsPage: FC = () => {
           })()}
         </>
       ) : (
-        <p class="empty">No trend analysis yet — run <code>python3 ingest/analyze_trends.py</code> (the opportunity-scan module does this daily).</p>
+        <p class="empty">No trend analysis yet — run <code>n-seo daily --only opportunity-scan</code>, which refreshes it (the daily run does this for you when the module is on).</p>
       )}
     </>
   );
@@ -976,7 +976,7 @@ export const ContentPage: FC = () => {
                   ))}
                 </div>
               ) : (
-                <p class="empty">No fresh threads — the daily run refreshes this list (<code>python3 ops/hn_digest.py</code> any time).</p>
+                <p class="empty">No fresh threads — the daily run refreshes this list (<code>n-seo daily --only hn-digest</code> any time).</p>
               )}
             </>
           )}
@@ -1216,7 +1216,7 @@ export const LogsPage: FC = () => {
           <h2>{sec.heading}</h2>
           <ul class="log-lines">{sec.lines.map(logLine)}</ul>
         </div>
-      )) : <p class="empty">No daily-log entries yet — <code>python3 ops/daily.py</code> writes <code>docs/daily-log.md</code>.</p>}
+      )) : <p class="empty">No daily-log entries yet — <code>n-seo daily</code> writes <code>docs/daily-log.md</code>.</p>}
 
       <h2>Raw run output <small>(data/daily-ops.log, last 150 lines — look here if a run failed)</small></h2>
       <div class="tbl-wrap"><pre class="ops-log">{data.opsLogTail()}</pre></div>
@@ -1403,7 +1403,7 @@ export const TrendsPage: FC<{ days: number }> = ({ days }) => {
               <span class="domain">{site.host}</span>
               <span class="chip">{site.gscProperty ? "Search Console connected" : "no Search Console property"}</span>
               <span class="chip">{site.ga4Property ? "GA4 connected" : "no GA4 property"}</span>
-              <span class="trend-empty-note">no time series yet — run <code>python3 ingest/pull_timeseries.py</code></span>
+              <span class="trend-empty-note">no time series yet — run <code>n-seo daily --only timeseries</code></span>
             </div>
           );
         }