seo 0.0.15 → 0.2.0

package/README.md

@@ -1,51 +1,447 @@
-# node-seo [![Build Status](https://travis-ci.org/saschagehlich/node-seo.svg?branch=master)](https://travis-ci.org/saschagehlich/node-seo)
+<p align="center">
+  <img src="apps/web/public/favicon.svg" alt="SEO Skill" width="72" height="72">
+</p>
 
-node-seo is a connect middleware that can generate, cache and serve HTML
-snapshots of single page web apps for search bots. Uses [PhantomJS](http://phantomjs.org/)
-for generating snapshots.
+<h1 align="center">SEO Skill</h1>
 
-## Installation
+<p align="center">
+  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.
+</p>
 
-via npm:
+<p align="center">
+  <a href="#quick-start">Get started</a>
+  ·
+  <a href="https://seoskill.dev/docs">Documentation</a>
+  ·
+  <a href="https://www.npmjs.com/package/seo">npm</a>
+  ·
+  <a href="https://github.com/iannuttall/seo/issues">Questions</a>
+  ·
+  <a href="https://seoskill.dev/privacy">Privacy</a>
+  ·
+  <a href="SECURITY.md">Security</a>
+  ·
+  <a href="LICENSE">License</a>
+  ·
+  <a href="AGENTS.md">Agent notes</a>
+</p>
 
-```bash
-$ npm install seo
+<p align="center">
+  <a href="https://github.com/iannuttall/seo/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/github/actions/workflow/status/iannuttall/seo/ci.yml?branch=main&label=checks&style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/seo"><img alt="npm version" src="https://img.shields.io/npm/v/seo?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/seo"><img alt="npm downloads" src="https://img.shields.io/npm/dm/seo?style=flat-square"></a>
+  <img alt="Node 22 or newer" src="https://img.shields.io/badge/Node-22%2B-339933?style=flat-square">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-3178c6?style=flat-square">
+  <a href="LICENSE"><img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?style=flat-square"></a>
+</p>
+
+The `seo` command runs a full SEO audit from your terminal, turning a local
+crawl and your own search data into work you can inspect and ship. Find
+technical blockers, recover search demand, improve pages already close to more
+clicks, and catch regressions after a release.
+
+## Who this is for
+
+- People running their own sites who want a clear audit and a ranked list of
+  fixes, without learning a heavy dashboard.
+- AI agents that need real crawl, Search Console, and GA4 evidence through MCP
+  and one packaged SEO skill instead of screenshots or guesses.
+- Developers who want to embed the same report engine in a script, a CI job, or
+  a TypeScript app.
+
+## Quick start
+
+Requires Node 22 or newer.
+
+```sh
+npm i -g seo
+seo start
+seo report
+```
+
+The setup walks you through Google sign-in, your Search Console property, an
+optional GA4 property, and a local project profile. Public releases can include
+the shared Google app. If it is unavailable in your build, setup guides you
+through adding your own desktop OAuth client.
+
+That is the normal path. The `seo` command is then available in every terminal,
+script, CI job, and local MCP client on the machine.
+
+The main report uses the evidence you have, explains what it could not check,
+and recommends a short list of follow-up commands. You can start with a local
+technical report before connecting Google.
+
+Running `seo help` shows the shape of the tool:
+
+```txt
+seo v0.2.0
+
+Human-friendly SEO reports first, power tools when you need them.
+
+Start here
+  seo start                                Connect Google and save a project profile
+  seo report                               Run the main SEO report for the default project
+  seo report --site sc-domain:example.com  Run without a profile
+  seo report --url https://example.com     Start with a local technical report
+
+Projects
+  seo projects list  List saved project profiles
+  seo projects add   Create or update a project profile
+  seo sites          List Search Console properties
+  seo doctor         Check local auth and config
+
+Act on a report
+  seo refresh-priorities  Rank the next best SEO actions
+  seo quick-wins          Find ranking 4-10 low-CTR wins
+  seo second-page         Investigate URLs averaging positions 10-20
+  seo technical-watch     Crawl and index-monitor a site
+
+Agent and power tools
+  seo report --json    Run the main report as structured JSON
+  seo export diagnose  Export report data to CSV
+  seo mcp install      Install SEO tools into MCP clients
+  seo skill list       Show the packaged SEO skill
+  seo reports list     Discover every structured report
+
+Use `seo help <command>` or `seo <command> --help` for command help.
+Use `seo help all` for the longer command list.
+```
+
+## What you get
+
+- Find technical blockers across metadata, links, indexability, canonicals,
+  structured data, performance, security, mobile, international SEO, and
+  social previews.
+- Rank the work using affected URLs, rule severity, search visibility, and
+  analytics value instead of treating every warning equally.
+- See why a finding matters, what evidence supports it, how to fix it, and how
+  to verify the change.
+- Save and compare crawl reports without running the same crawl again.
+- Measure SEO changes with matched before and after Search Console windows.
+- Give scripts and agents deterministic JSON, Markdown, stable rule IDs, and a
+  compact local MCP surface.
+
+## How the reports stay honest
+
+The point of a report is to be defensible, so the design keeps a few rules:
+
+- Observed evidence stays separate from derived findings and recommended
+  actions. You can always see the crawl row or provider row behind a claim.
+- Partial data is never reported as a zero. A capped, filtered, or sampled
+  source says so, and it cannot support a definitive all-clear.
+- Heuristics are labeled as heuristics. A convention or threshold is not
+  presented as a search-engine rule.
+- Each recommendation comes with a way to check that the fix worked, rather than
+  a promise about rankings or traffic.
+
+## Everyday use
+
+`seo start` can save a project profile, which is a local shortcut for a site,
+Search Console property, GA4 property, and brand terms. If you have one default
+project, most commands need no flags.
+
+```sh
+seo report
+seo refresh-priorities
+seo quick-wins
+seo second-page
+seo technical-watch
+```
+
+Use `--project` when you have more than one:
+
+```sh
+seo report --project example
+seo projects list
+```
+
+You can also work without a saved profile:
+
+```sh
+seo report --site sc-domain:example.com
+seo report --url https://example.com
+seo crawl https://example.com
+seo audit-page --url https://example.com/pricing
+```
+
+`seo report --url` crawls the site and saves technical evidence. It does not
+pretend to know traffic, queries, or rankings until you add a Search Console
+property with `seo start`.
+
+Run `seo help` for the short path or `seo help all` for the full command list.
+
+## Crawl a site
+
+Run a readable technical crawl, the base of any technical SEO audit:
+
+```sh
+seo crawl https://example.com --format pretty
+```
+
+Save it, export it, or compare it with an earlier crawl:
+
+```sh
+seo crawl https://example.com --save
+seo crawl https://example.com --format html --output report.html
+seo crawl-reports
+seo crawl-reports --compare latest --against previous
+```
+
+Useful crawl controls include `--max-pages`, `--max-depth`, `--include`,
+`--exclude`, `--no-sitemap`, `--no-external`, and `--fail-on` for CI.
+
+## Use it in CI and scripts
+
+JSON mode never prompts. Pass the site or project explicitly in unattended
+runs.
+
+```sh
+seo report --project example --json
+seo crawl https://example.com --json --output crawl.json
+seo crawl https://example.com --fail-on high --json
+```
+
+Reports keep observed data, derived findings, skipped sections, limits, and
+provider errors separate so automation can make decisions without parsing
+terminal prose.
+
+`seo report --json` returns a compact summary, action queue, and bounded crawl
+evidence so an agent can choose its next call without loading every raw report.
+Use `--full` only when a script needs the complete report object.
+
+When a CI job needs Search Console or GA4 data, give it a Google service
+account JSON key through its secret store. The service account needs access to
+the exact properties it will query. This GitHub Actions step runs without a
+browser or a copied local token:
+
+```yaml
+- name: Run the SEO report
+  run: |
+    npm i -g seo
+    seo report --site sc-domain:example.com --json > seo-report.json
+  env:
+    SEO_GOOGLE_SERVICE_ACCOUNT_JSON: ${{ secrets.SEO_GOOGLE_SERVICE_ACCOUNT_JSON }}
+```
+
+The [Google data guide](https://seoskill.dev/docs/google) covers Search
+Console and GA4 permissions, mounted secret files, and how to check the active
+identity safely.
+
+Agents can discover and run the same report catalog as MCP without starting a
+server:
+
+```sh
+seo reports list --category crawl --json
+seo reports describe audit-page --json
+seo reports run audit-page --params '{"url":"https://example.com"}' --json
+```
+
+Always describe a report before constructing its parameters. The CLI and MCP
+surfaces read from the same registry, so their ids and JSON Schemas cannot
+drift.
+
+## Use it with AI agents
+
+Your agent carries one short SEO skill, and the CLI and MCP server do the
+heavy lifting. The skill teaches an agent how to discover the 50+ audit and
+report tools at runtime, and the agent asks the CLI for the detail on each
+tool only when it is about to run it. You get the whole toolkit without fifty
+skill files sitting in the context window on every session.
+
+`seo start` offers to install the SEO skill during setup. In an agent-managed
+environment, add it yourself with the standard installer:
+
+```sh
+npm i -g seo
+npx skills add iannuttall/seo
+```
+
+Then install the local stdio MCP server into a supported client:
+
+```sh
+seo mcp install
+```
+
+The prompt detects installed clients. Scripts can choose one or more explicitly:
+
+```sh
+seo mcp install --codex
+seo mcp install --claude-code
+seo mcp install --cursor
+seo mcp install --claude-desktop
+```
+
+Your client starts the server when it needs it. Run it directly only for manual
+configuration or testing:
+
+```sh
+seo mcp serve
 ```
 
-## Configuration
+The repository ships one skill under `skills/seo`. It is a router: it teaches an
+agent to discover reports, describe one to load its depth at runtime, inspect
+the evidence, and request a smaller follow-up instead of loading a giant result
+into context. Per-report guidance lives in the registry and is fetched with
+`seo reports describe <id> --json`, so it never drifts from the skill.
+
+The npm package includes the same file for local inspection:
+
+```sh
+seo skill list
+seo skill path seo
+```
+
+Agents can also discover the canonical skill from
+`https://seoskill.dev/.well-known/agent-skills/index.json`. The entry links to
+the canonical skill instructions and includes a content digest for verification.
+
+See [MCP and agents](https://seoskill.dev/docs/agents) for setup and tool
+details.
 
-node-seo can be used as a middleware for connect/express, like this:
+## Use it as a library
 
-```js
-var express = require('express');
-var seo  = require('seo');
-var app = express();
+Install the same unscoped package in any Node 22 or newer project:
 
-app.use(new seo({
-  cacheDirectory: path.resolve(process.cwd(), '.seo-cache'),
-  routes: require('./seo-routes'),
-  requestURL: 'http://localhost:8080',
-  pageModifier: function (page, callback) {
-    // This function can be used to modify a page before it is cached
-    // `page` is an instance of PhantomJS's Page object. For an example
-    // see `test/middleware.test.js`
-  }
-}).init());
+```sh
+npm install seo
+```
+
+Run any public report by id with the same definition, input schema, and
+evidence used by the CLI and MCP server:
+
+```ts
+import { describeReport, executeReport } from 'seo/mcp'
+
+const description = describeReport('quick-wins')
+const result = await executeReport('quick-wins', {
+  site: 'sc-domain:example.com',
+  days: 90,
+})
 
-app.listen(8080);
+console.log(description.inputSchema)
+console.log(result)
 ```
 
-In this case, node-seo will use `seo-routes.js` to check whether it should
-create a snapshot for the current path. This file should export a function that
-returns a boolean. The first parameter is the current request:
+Or call typed analysis functions directly when your app already knows the job
+it needs to run:
+
+```ts
+import { auditPage, crawlSite } from 'seo'
+
+const page = await auditPage({
+  url: 'https://example.com/pricing',
+})
+
+const crawl = await crawlSite({
+  url: 'https://example.com',
+  maxPages: 100,
+  maxDepth: 4,
+})
 
-```js
-module.exports = function (request) {
-  if (request.path === '/') return true;
-  return false;
-}
+console.log(page.issues)
+console.log(crawl.summary, crawl.issueGroups)
 ```
 
-## Todo
+The main `seo` export contains the report, provider, crawler, storage, and
+rendering APIs. `seo/mcp` exposes report discovery, report execution, and the
+embeddable MCP server. See the [TypeScript library
+guide](https://seoskill.dev/docs/library) for structured error handling,
+local Google access, and more examples.
+
+## Local data and Google access
+
+Google OAuth tokens use your system keychain when it is available. On a
+headless machine or a locked keychain, the CLI falls back to a private
+`0600` file in your user config directory. Project profiles, crawl reports, and
+provider caches are also local. Use these commands to inspect or remove them:
+
+```sh
+seo privacy
+seo doctor
+seo auth logout
+seo reset
+```
+
+`seo auth status` shows the active storage mode. Power users can choose it with
+`seo auth storage --keychain` or `seo auth storage --file`.
+
+Power users can bring their own Google OAuth client. See
+[getting started](https://seoskill.dev/docs/getting-started) for the available
+auth paths.
+
+## Common questions
+
+### Does my site data stay on my machine?
+
+Yes. Reports, project profiles, Google tokens, crawls, and caches stay in your
+local config directory. The CLI only makes the network requests needed to fetch
+your site and call the Google APIs you connect. There is no hosted backend,
+account, or telemetry service.
+
+### Do I need a Google API key?
+
+No. `seo start` uses a normal Google sign-in for read-only Search Console and
+GA4 access. Public releases can include a shared desktop OAuth client, and if
+your build does not have one, setup helps you add your own. You can also run a
+local technical crawl with no Google connection at all.
+
+### What does it cost?
+
+The `seo` package is free and open source under Apache-2.0. It calls Google APIs
+you already have access to, so there is no separate subscription. Your own API
+quotas still apply.
+
+### How is this different from a paid SEO tool?
+
+A hosted SEO tool keeps your data on its servers and shows you a dashboard. This
+runs on your machine, works from your own crawl and Google data, and returns
+structured evidence your agent can read and act on. Every finding shows the
+evidence behind it and a way to verify a fix, so you are not trusting a score
+you cannot inspect.
+
+## Documentation
+
+Questions, bug reports, and feature requests go through
+[GitHub Issues](https://github.com/iannuttall/seo/issues). Report suspected
+vulnerabilities privately through the process in [SECURITY.md](SECURITY.md).
+
+- [Getting started](https://seoskill.dev/docs/getting-started)
+- [CLI commands](https://seoskill.dev/docs/cli)
+- [Crawler](https://seoskill.dev/docs/crawler)
+- [Reports and data](https://seoskill.dev/docs/reports)
+- [MCP and agents](https://seoskill.dev/docs/agents)
+- [AI-search evidence](https://seoskill.dev/docs/ai-search)
+- [Privacy policy](https://seoskill.dev/privacy)
+- [Terms of use](https://seoskill.dev/terms)
+- [Security policy](https://seoskill.dev/security)
+- [Contributing](CONTRIBUTING.md)
+- [Trademark and brand policy](TRADEMARKS.md)
+
+## Develop locally
+
+Most users do not need the source checkout. If you want to contribute:
+
+```sh
+git clone https://github.com/iannuttall/seo.git
+cd seo
+pnpm install
+pnpm build
+node dist/cli.js start --dry-run
+```
+
+Run the full quality gate before opening a pull request:
+
+```sh
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+pnpm pack --dry-run
+```
+
+Contributor architecture and report-quality rules live in [AGENTS.md](AGENTS.md).
+
+## License
 
-* Ability to pre-render (initial rendering can take some time and we don't want to affect our search engine ranking by slow rendering times)
+The code is available under [Apache-2.0](LICENSE). Project names and artwork are
+covered separately by the [trademark and brand policy](TRADEMARKS.md).

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security
+
+## Report a vulnerability
+
+Do not open a public issue for a suspected vulnerability.
+
+Use GitHub's private vulnerability reporting flow:
+
+```txt
+https://github.com/iannuttall/seo/security/advisories/new
+```
+
+Include the affected command, package, or workflow, clear reproduction steps,
+and the practical impact. Remove Google tokens, API keys, account identifiers,
+analytics data, private URLs, and client data from every example.
+
+Use [GitHub Issues](https://github.com/iannuttall/seo/issues) for ordinary
+questions and non-sensitive bugs.
+
+## Local data and credentials
+
+`seo` is local-first. Project profiles, Google OAuth metadata, crawl reports,
+and caches stay on the machine running the command. Access and refresh tokens
+use the operating-system keychain when enabled; fallback token files and local
+credential files use private file permissions.
+
+Desktop OAuth client credentials are not confidential secrets. User tokens,
+provider API keys, and analytics data are confidential and must never be
+committed, pasted into issues, or included in fixtures.
+
+Use `seo privacy` to inspect local storage and `seo reset --yes` to remove it.
+Google grants can also be revoked at
+<https://myaccount.google.com/connections>.
+
+## Maintainer checks
+
+Before a public release or a change to auth, storage, crawling, or provider
+boundaries, run:
+
+```sh
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+pnpm security:check
+pnpm pack --dry-run
+```
+
+The shared desktop OAuth client values are release build inputs. Store them as
+GitHub Actions secrets so they are injected only into the release build.
+Checked-in generated OAuth files must contain placeholders only.
+
+`pnpm security:check` runs the dependency audit and gitleaks. On macOS the
+helper installs gitleaks with Homebrew when it is missing. Other platforms must
+install gitleaks first.

package/TERMS.md

@@ -0,0 +1,94 @@
+# Terms of use
+
+Last updated: 10 July 2026
+
+These terms cover the official `seo` command-line tool, library, MCP server,
+documentation, and seoskill.dev website.
+
+## Open source licence
+
+The software is licensed under the [Apache License
+2.0](https://github.com/iannuttall/seo/blob/main/LICENSE). That licence controls
+your right to use, copy, modify, and distribute the code. Third-party packages
+keep their own licences.
+
+These terms do not take away rights granted by an applicable open source
+licence. They cover use of the official website, documentation, name, Google
+integration, and distributed project services that sit outside the source-code
+licence.
+
+## Use the tool responsibly
+
+You are responsible for the commands you run and the sites, accounts, and data
+you use with them. Only crawl, inspect, or analyse a site when you are allowed
+to do so. Follow applicable laws, access controls, robots policies, provider
+terms, and reasonable rate limits.
+
+Do not use the project to gain unauthorised access, disrupt a service, evade a
+technical restriction, expose another person's data, or carry out unlawful
+activity.
+
+## Google and other third-party services
+
+Google Search Console and Google Analytics access is optional and read-only.
+Your use of Google APIs is also subject to Google's terms and policies. Google
+can change API behaviour, quotas, scopes, or availability without notice to
+this project.
+
+The software can request public websites, run browser tooling, and use package
+registries or operating system services. Those products are controlled by
+their respective operators. The project is not responsible for their content,
+availability, security, or data practices.
+
+## Reports are evidence, not a guarantee
+
+SEO reports can be incomplete because websites change, providers retain or cap
+data, crawls stop, and search systems do not publish every ranking signal. The
+software is designed to show those limits, but bugs and incorrect findings are
+still possible.
+
+Reports are general technical information. They do not promise rankings,
+traffic, revenue, indexing, rich results, AI citations, or any other outcome.
+Check important findings against the live site and the relevant provider before
+making a consequential change.
+
+## Your local data
+
+You are responsible for protecting local tokens, configuration, caches,
+reports, exports, backups, and environment variables. Keep secrets out of
+public issues, logs, screenshots, repositories, and shared report files.
+
+The [privacy policy](https://seoskill.dev/privacy) explains what the software
+stores and how to remove it.
+
+## Availability and changes
+
+The project may change commands, reports, integrations, or documentation in a
+future release. A feature can be fixed, replaced, or removed when needed for
+security, correctness, provider policy, or maintainability.
+
+There is no promise that the website, package registry, Google integration, or
+project support will always be available.
+
+## Warranty and liability
+
+The software and website are provided without warranties or guarantees. The
+Apache License 2.0 contains the warranty and liability terms for the licensed
+software.
+
+To the fullest extent allowed by applicable law, the project maintainer is not
+liable for indirect, incidental, special, consequential, or business losses
+arising from use of the software, website, reports, or third-party services.
+Nothing in these terms excludes liability that cannot legally be excluded.
+
+## Changes to these terms
+
+The date at the top will be updated when these terms change. Earlier versions
+remain available in the public Git history. Continued use after a change means
+the new terms apply to later use.
+
+## Questions about these terms
+
+Open an issue in the [public GitHub repository](https://github.com/iannuttall/seo/issues).
+Do not include OAuth tokens, private reports, personal data, or other secrets in
+a public issue.

package/TRADEMARKS.md

@@ -0,0 +1,31 @@
+# Trademark and brand policy
+
+The source code is available under Apache-2.0. That license does not grant a
+right to present another product or service as the official `seo` project.
+
+This policy covers this project's identity: the name `seo` when it refers to
+this specific package and project, the tagline "The SEO command for AI agents",
+the logo and project artwork, and seoskill.dev.
+
+"seo" is a generic term for search engine optimization. This policy claims no
+rights over that generic use. It covers only the project's name in context, its
+logo, its branding, and its tagline.
+
+## Uses that are fine
+
+- Truthfully saying that software uses, supports, or is based on `seo`.
+- Linking to the official repository or seoskill.dev.
+- Keeping required attribution and notices in copies or forks.
+- Describing a fork as an unofficial fork, provided the distinction is clear.
+
+## Ask first
+
+Open a [GitHub Issue](https://github.com/iannuttall/seo/issues) before using the
+project name or artwork as the main identity of a product, company, hosted
+service, domain, package, event, or merchandise.
+
+Do not imply endorsement, partnership, or official status. Forks and hosted
+versions must use a distinct name and visual identity, and must not create
+confusion with the npm package, repository, or seoskill.dev.
+
+Nominative and other uses allowed by applicable law remain allowed.