seo 0.0.15 → 0.2.0

package/package.json

@@ -1,36 +1,116 @@
 {
   "name": "seo",
-  "version": "0.0.15",
-  "description": "A connect middleware that serves html snapshots of single page apps",
-  "main": "index.js",
-  "scripts": {
-    "test": "make test"
-  },
+  "version": "0.2.0",
+  "description": "The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and GA4 data.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Ian Nuttall",
+  "homepage": "https://seoskill.dev",
   "repository": {
     "type": "git",
-    "url": "git://github.com/saschagehlich/node-seo.git"
+    "url": "git+https://github.com/iannuttall/seo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iannuttall/seo/issues"
   },
+  "funding": "https://github.com/iannuttall/seo",
   "keywords": [
-    "snapshot",
-    "phantom",
-    "search",
-    "bots"
+    "seo",
+    "search-console",
+    "google-analytics",
+    "crawler",
+    "cli",
+    "mcp"
   ],
-  "author": "Sascha Gehlich <sascha@gehlich.us>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/saschagehlich/node-seo/issues"
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "seo": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "evals",
+    "PRIVACY.md",
+    "SECURITY.md",
+    "TERMS.md",
+    "TRADEMARKS.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "pnpm@11.11.0",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "auth:inject-shared-client": "node scripts/inject-shared-oauth-client.mjs",
+    "build": "turbo run build && pnpm run build:package",
+    "build:package": "tsdown --config tsdown.config.ts",
+    "clean": "turbo run clean && rm -rf dist",
+    "dev": "turbo run dev",
+    "lint": "biome check . && node scripts/check-emdashes.mjs && node scripts/check-report-parity.mjs && pnpm run skills:validate && turbo run lint",
+    "lint:fix": "biome check . --write",
+    "loc:audit": "node scripts/loc-audit.mjs",
+    "pack:check": "pnpm pack --dry-run",
+    "prepack": "pnpm run skills:validate && pnpm run build:package && node --test scripts/package.test.mjs",
+    "security:audit": "pnpm audit --audit-level low",
+    "security:check": "pnpm run security:audit && pnpm run security:secrets",
+    "security:secrets": "node scripts/security-secrets.mjs",
+    "skills:validate": "node scripts/validate-skills.mjs",
+    "test": "turbo run test && pnpm run build:package && node --test scripts/package.test.mjs && pnpm run skills:validate",
+    "test:package-install": "pnpm run build:package && node --test scripts/installed-package.test.mjs",
+    "typecheck": "turbo run typecheck"
   },
-  "homepage": "https://github.com/saschagehlich/node-seo",
   "dependencies": {
-    "underscore": "~1.6.0",
-    "phantom": "~0.6.1",
-    "q": "~1.0.1"
+    "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "^0.6.0",
+    "@napi-rs/keyring": "^1.3.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.20.1",
+    "better-sqlite3": "^12.11.1",
+    "citty": "^0.2.2",
+    "cli-table3": "^0.6.5",
+    "consola": "^3.4.2",
+    "debug": "^4.4.3",
+    "defuddle": "^0.19.1",
+    "jsonc-parser": "^3.3.1",
+    "lighthouse": "13.4.0",
+    "linkedom": "^0.18.13",
+    "open": "^11.0.0",
+    "p-queue": "^9.3.1",
+    "p-retry": "^8.0.0",
+    "picocolors": "^1.1.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "playwright-core": "1.61.1",
+    "proper-lockfile": "^4.1.2",
+    "robots-parser": "^3.0.1",
+    "schema-dts": "^2.0.0",
+    "undici": "^8.7.0",
+    "update-notifier": "^7.3.1",
+    "user-agents": "2.1.117",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "should": "~3.3.1",
-    "mocha": "~1.18.2",
-    "supertest": "~0.12.0",
-    "express": "~4.1.2"
+    "@biomejs/biome": "^2.5.3",
+    "@changesets/cli": "^2.31.0",
+    "tsdown": "^0.22.4",
+    "turbo": "^2.10.4",
+    "typescript": "^6.0.3"
   }
 }

package/skills/README.md

@@ -0,0 +1,68 @@
+# Agent skills
+
+This package ships one skill: `seo`. It teaches an agent how to use `seo`
+without reading the whole repo.
+
+The skill is a router, not a manual. It explains the discover, describe, run
+flow, names the report ids for common jobs, and states the evidence rules that
+apply to every report. It does not memorise each report. Per-report depth, when
+to use a report, when to avoid it, its schema, the order to read its output,
+what its evidence cannot support, and one verification step, is fetched at
+runtime with `describe`. This keeps the skill small and always in sync with the
+registry.
+
+## Install
+
+The skill works best with the MCP server installed. This command is an
+interactive setup flow for a human:
+
+```bash
+seo mcp install
+```
+
+The skill also works by calling the CLI directly when MCP tools are not
+available. The npm package and repository contain the same skill. Install it
+with the standard agent skills installer:
+
+```bash
+npx skills add iannuttall/seo
+```
+
+Use `seo skill list` or `seo skill path seo` to inspect the copy bundled with
+the npm package.
+
+## Discover, describe, run
+
+The MCP path is deliberately small: discover ids with `seo_list_reports`, load
+one report's full depth with `seo_describe_report`, then execute it with
+`seo_run_report`. The same catalog is available without MCP:
+
+```bash
+seo reports list --json
+seo reports describe <report-id> --json
+seo reports run <report-id> --params '<json>' --json
+```
+
+Always describe a report before its first run. The describe response is the
+per-report manual: its `readOrder`, `doNotClaim` limits, `verify` step, and
+`related` ids come straight from the registry.
+
+## Adding a report
+
+Register the report once in `packages/mcp/src/report-registry.ts`, including its
+depth guidance in `packages/mcp/src/report-guidance.ts` and
+`packages/mcp/src/report-depth.ts` (`readOrder`, `doNotClaim`, `verify`,
+`related`). CLI discovery, MCP discovery, and the skill then share its id,
+description, input schema, handler, and depth automatically. No new skill file
+is needed. The router only lists report ids for common jobs; a report earns a
+mention there when it belongs in one of those chains.
+
+Run `pnpm skills:validate` after changing the skill or the registry. The
+validator checks the skill frontmatter and word count, that every command and
+report id the skill names resolves, that the MCP tool names are real, and that
+every `evals/*.json` is well formed.
+
+## Evals
+
+Behaviour tests for the skill live in the top-level `evals/` directory. See
+[../evals/README.md](../evals/README.md) for the file shape and how to run them.

package/skills/seo/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: seo
+description: Use and read this skill immediately if the user request is in any way related to SEO or a site's organic search or AI search presence. That includes site audits, rankings, click or traffic changes, indexing problems, crawling, redirects, sitemaps, metadata, structured data, Core Web Vitals, internal links, content opportunities, Search Console or GA4 questions, Google update impact, llms.txt, AI search visibility in ChatGPT, Claude, Perplexity, or Google AI Overviews, and client SEO reporting. Routes to 52 evidence-backed local reports through the SEO CLI and MCP server.
+---
+
+# seo
+
+`seo` is a local CLI, MCP server, and report engine. It answers SEO questions
+with evidence from three sources: its own crawl of the site, Google Search
+Console, and GA4. Every report returns structured JSON with the observed
+evidence, derived findings, caveats, and provenance kept separate. Nothing is
+hosted; data stays on the machine.
+
+You do not need to memorise reports. Discover them at runtime.
+
+## Discover, describe, run
+
+With the MCP server (preferred):
+
+1. `seo_list_reports` returns every report id with a one-line purpose,
+   optionally by category.
+2. `seo_describe_report` with one id returns when to use it, when to avoid it,
+   its exact JSON Schema, the order to read its output in, what its evidence
+   cannot support, one verification step, and related report ids.
+3. `seo_run_report` with the id and a bounded `params` object. Read
+   `structuredContent`, not the display text.
+
+The same catalog exists without MCP:
+
+```bash
+seo reports list --json
+seo reports describe <report-id> --json
+seo reports run <report-id> --params '<json>' --json
+```
+
+Always describe a report before its first run in a session. The describe
+response is the per-report manual: follow its `readOrder`, respect its
+`doNotClaim` limits, and use its `related` ids to decide what to run next.
+Reuse the schema for repeated runs. Do not guess parameters.
+
+## Setup and selection
+
+Run the `setup-check` report (or `seo doctor`) if auth state is unknown.
+Saved project profiles are selected with `--project <id>`; list them with
+`seo projects list --json`. Without a profile, pass `--site sc-domain:example.com`
+for Search Console reports or `--url https://example.com` for crawl-only
+reports. Crawl and page audits work with no Google connection at all. Always
+pass `--json`; JSON mode never prompts.
+
+## Common jobs
+
+Each job lists report ids in a sensible starting order. Run the first, read
+its evidence, then decide; do not run a whole chain blindly.
+
+| Job | Reports |
+|---|---|
+| Page not indexed or missing from Google | `index-coverage`, `index-monitor` (URL Inspection), `audit-page`, `redirect-trace` |
+| Traffic or clicks dropped | `search-performance-overview`, `traffic-anomaly`, `update-correlation`, `segment-impact`, `decaying-pages`, `link-recovery` |
+| Audit a whole site | `report` command (main report), `site-crawl`, `top-fixes`, `ai-search-scorecard` |
+| More clicks from existing pages | `quick-wins`, `ctr-underperformers`, `striking-distance`, `second-page`, `internal-links` |
+| AI search visibility and readiness | `ai-search-scorecard`, `ai-readiness`, `geo-gaps`, `entity-readiness`, `llms-txt-audit`, `ai-referrals` |
+| Plan content from real demand | `query-clusters`, `page-opportunities`, `content-optimization`, `cannibalisation` |
+| Catch regressions over time | `technical-watch`, `crawl-diff`, `index-watch`, `measure-change` after a fix ships |
+| Client-ready reporting | `monthly-report`, `narrative-report`, `monthly-action-plan` |
+| Turn crawl findings into tickets | `top-fixes`, `affected-urls`, `explain-crawl-issue` |
+
+A single page complaint usually needs both angles: the index evidence for that
+URL and an `audit-page` pass for content or technical problems on the page
+itself.
+
+The main human report is the `seo report` command. It is the right first move
+when the user asks a broad "how is my site doing" question; the focused
+reports above are for specific symptoms.
+
+## Evidence rules
+
+- Check `dataStatus`, selection counts, `caveats`, and `warnings` before
+  summarising any report. Name skipped or incomplete evidence first.
+- Partial, capped, filtered, or sampled sources never support a zero or an
+  all-clear. Grouped Search Console totals undercount because anonymised query
+  rows are withheld.
+- Values marked heuristic are prioritisation aids, not forecasts. Never
+  promise clicks, rankings, indexing, or AI citations from any report.
+- Quote `principle` and `evidenceRef` when explaining a recommendation, and
+  give the user the report's verification step alongside any suggested change.
+- If a report returns no rows, say so plainly.
+- Intentional controls such as `noindex`, canonicals, and robots rules are
+  observations until the user confirms they are unintended.
+
+## Beyond the report catalog
+
+The CLI also has direct commands for raw provider access and administration:
+`seo gsc-query`, `seo url-inspect`, `seo ga4-report`, `seo updates`,
+`seo crawl`, `seo export`, and `seo projects`. Use `seo help all` to list
+everything. Prefer a registered report when one covers the question, because
+reports carry provenance and caveats that raw queries do not.
+
+Report output is cached locally. Pass `refresh: true` (or `--refresh`) only
+when the user explicitly wants a fresh fetch.

package/skills/seo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "seo"
+  short_description: "Use immediately for anything touching SEO, organic search, or AI search: audits, rankings, traffic changes, indexing, crawling, Search Console, GA4, or AI visibility"
+  default_prompt: "Use $seo to discover, describe, and run the right local SEO report and explain its evidence."

package/.jshintrc

@@ -1,18 +0,0 @@
-{
-  "globals"   : {
-    /* MOCHA */
-    "describe"   : false,
-    "it"         : false,
-    "before"     : false,
-    "beforeEach" : false,
-    "after"      : false,
-    "afterEach"  : false,
-
-    /* COMMONJS / NODE */
-    "module"     : false,
-    "require"    : false,
-    "console"    : false,
-    "process"    : false,
-    "global"     : false
-  }
-}

package/.npmignore

@@ -1,3 +0,0 @@
-.DS_Store
-node_modules
-.seo-cache

package/.travis.yml

@@ -1,3 +0,0 @@
-language: node_js
-node_js:
-  - "0.10"

package/Makefile

@@ -1,10 +0,0 @@
-REPORTER = spec
-
-test:
-	@./node_modules/.bin/mocha \
-		--require ./test/init.js \
-		--require should \
-		--reporter $(REPORTER) \
-		test/*.test.js
-
-.PHONY: all test

package/index.js

@@ -1,2 +0,0 @@
-'use strict';
-module.exports = require('./lib/seo');

package/lib/middleware.js

@@ -1,159 +0,0 @@
-/* global document */
-'use strict';
-
-var fs = require('fs');
-var path = require('path');
-var crypto = require('crypto');
-var phantom = require('phantom');
-var Q = require('q');
-
-function Middleware(options) {
-  this.options = options;
-}
-
-/**
- * Handles the given request
- * @param  {Request}   req
- * @param  {Response}   res
- * @param  {Function} next [description]
- * @public
- */
-Middleware.prototype.request = function (req, res, next) {
-  var self = this;
-  var shouldTakeSnapshot = this.options.routes(req);
-  if (!shouldTakeSnapshot) return next();
-
-  var botRegex = /(google|yahoo|bing|baidu|jeeves|facebook|twitter|linkedin|xovibot)/i;
-  var isBot = botRegex.test(req.headers['user-agent']);
-  if (!isBot) return next();
-
-  this._checkForCache(req)
-    .then(function (inCache) {
-      if (!inCache) {
-        return self._createSnapshot(req);
-      }
-    })
-    .then(function () {
-      return self._serveSnapshot(req, res);
-    });
-};
-
-Middleware.prototype._serveSnapshot = function(request, response) {
-  var cachePath = this._getCachePathForRequest(request);
-  fs.readFile(cachePath, function (err, data) {
-    if(err) throw err;
-    response.send(data.toString());
-  });
-};
-
-Middleware.prototype._createSnapshot = function(request) {
-  var self = this;
-  var deferred = Q.defer();
-  var cachePath = this._getCachePathForRequest(request);
-
-  var url = request.protocol + '://' + request.get('host') + request.originalUrl;
-  this._ensureCacheDirectoryExists()
-    .then(function () { return self._getContentForURL(url); })
-    .then(function (content) {
-      fs.writeFile(cachePath, content, function (err) {
-        if (err) return deferred.reject(err);
-        deferred.resolve();
-      });
-    });
-  return deferred.promise;
-};
-
-Middleware.prototype._checkForCache = function (request) {
-  var deferred = Q.defer();
-
-  // Does a cache file exist for this hash?
-  var cachePath = this._getCachePathForRequest(request);
-  fs.exists(cachePath, function (exists) {
-    deferred.resolve(exists);
-  });
-
-  return deferred.promise;
-};
-
-Middleware.prototype._getCachePathForRequest = function(request) {
-  var requestedPath = request.path;
-  var requestedHost = request.host;
-  var hash = this._getHashForUrl(requestedHost, requestedPath);
-
-  return path.resolve(this.options.cacheDirectory, hash);
-};
-
-Middleware.prototype._ensureCacheDirectoryExists = function() {
-  var self = this;
-  var deferred = Q.defer();
-  fs.exists(this.options.cacheDirectory, function (exists) {
-    if (!exists) {
-      fs.mkdir(self.options.cacheDirectory, function (err) {
-        if (err) return deferred.reject(err);
-        deferred.resolve();
-      });
-    } else {
-      deferred.resolve();
-    }
-  });
-  return deferred.promise;
-};
-
-/**
- * Returns an MD5 hash for the given path
- * @param  {String} host
- * @param  {String} path
- * @return {String}
- * @private
- */
-Middleware.prototype._getHashForUrl = function (host, path) {
-  return crypto.createHash('md5').update(host + '/' + path).digest('hex');
-};
-
-/**
- * Creates a PhantomJS instance and returns the computed DOM
- * for the given URL
- * @param  {String} url
- * @return {Promise}
- * @private
- */
-Middleware.prototype._getContentForURL = function (url) {
-  var deferred = Q.defer();
-  var self = this;
-  phantom.create(function (ph) {
-    ph.onError = function (err) {
-      ph.exit();
-      return deferred.reject(err);
-    };
-    ph.createPage(function (page) {
-      page.onError = function (err) {
-        ph.exit();
-        return deferred.reject(err);
-      };
-
-      page.open(url, function (status) {
-        if (status !== 'success') {
-          return deferred.reject(new Error('PhantomJS status for ' + url + ': ' + status));
-        }
-
-        var generateHTML = function () {
-          page.evaluate(function() { return document.documentElement.outerHTML; }, function (result) {
-            ph.exit();
-            deferred.resolve(result);
-          });
-        };
-
-        if (typeof self.options.pageModifier === 'function') {
-          self.options.pageModifier(page, function () {
-            generateHTML();
-          });
-        } else {
-          generateHTML();
-        }
-      });
-    });
-  });
-  return deferred.promise;
-};
-
-module.exports = Middleware;

package/lib/seo.js

@@ -1,32 +0,0 @@
-'use strict';
-
-var path = require('path');
-var _ = require('underscore');
-var Middleware = require('./middleware');
-
-function SEO(options) {
-  this.options = options;
-  this.options = _.defaults(this.options, {
-    cacheDirectory: path.resolve(process.cwd(), '.seo-cache')
-  });
-
-  if (!this.options.routes) {
-    this.options.routes = require(path.resolve(process.cwd(), 'seo-routes'));
-  }
-
-  this.middleware = new Middleware(this.options);
-}
-
-/**
- * Returns the middleware
- * @return {Function}
- * @public
- */
-SEO.prototype.init = function() {
-  var middleware = this.middleware;
-  return function() {
-    middleware.request.apply(middleware, arguments);
-  };
-};
-
-module.exports = SEO;

package/test/init.js

@@ -1,43 +0,0 @@
-'use strict';
-process.env.NODE_ENV = 'test';
-
-var path = require('path');
-var fs = require('fs');
-var _ = require('underscore');
-var express = require('express');
-var seo = require('../index');
-
-global._after = function (t, f) { return setTimeout(f, t); };
-global._every = function (t, f) { return setInterval(f, t); };
-
-global.createServer = function(options) {
-  var app = {};
-  var _seo = new seo(options);
-
-  app.server = express();
-  app.seo = _seo;
-  app.server.use(_seo.init());
-
-  app.server.get('/seo-route', function (req, res) {
-    var seoPagePath = path.resolve(process.cwd(), 'test/seo-page.html');
-    res.end(fs.readFileSync(seoPagePath));
-  });
-
-  app.server = app.server.listen(8899);
-
-  return app;
-};
-
-global.clearCache = function() {
-  var directory = path.resolve(process.cwd(), '.seo-cache');
-
-  if (!fs.existsSync(directory)) return;
-
-  var files = fs.readdirSync(directory);
-  files.forEach(function (file) {
-    var filePath = directory + '/' + file;
-    if (!fs.statSync(filePath).isDirectory()) {
-      fs.unlinkSync(filePath);
-    }
-  });
-};