pi-seo-guard0.3.0

pi-seo-guard

A Pi extension that stops the coding agent from silently wrecking your SEO. It diffs every edit/write of SEO-relevant files before it lands, blocks catastrophic changes, and feeds smaller regressions back to the agent so it fixes them in the same turn. Fully offline — no network, no API keys.

Demo

Install

pi install npm:pi-seo-guard
# or try without installing:
pi -e npm:pi-seo-guard

What it does

Rules

/seo-guard additionally uses: broken-link, sitemap-missing-route, missing-title, missing-description, missing-canonical (all warn).

Writes through bash

Since 0.1.1 the guard also looks at shell commands that modify watched SEO files: sed -i / sed -i.bak / perl -pi -e (simple s/// is applied in JS), > / >> redirects of echo / printf / cat / heredocs, tee [-a], cp / mv onto a watched file, truncate, and bash -c '…' wrappers. When the result can be computed it goes through the normal rules (e.g. sed -i 's/Allow/Disallow/' robots.txt → robots-disallow-all). When it can't (complex sed, $VAR, command output, scripts), a write to robots.txt or the root layout asks for confirmation (headless: blocked), and other watched files get a WARN. Reads (cat, grep, sed -n, sed without -i) and writes to unwatched paths never trigger.

Supported frameworks

/seo-guard

Scans the project (offline) and reports:

• broken internal links (<a href>, <Link>, markdown links) that match no route, static file or redirect
• routes missing from sitemap.xml
• routes present in git HEAD but gone now, with no redirect
• pages missing title / description / canonical (layout-provided values count)

The report is shown in the UI and queued as a hidden message for the agent's next turn.

Config — .pi/seo-guard.json

{
  "baseUrl": "https://example.com",
  "snapshotRoutes": true,
  "ignore": ["legacy/**", "**/*.stories.tsx", "public/vendor/**"],
  "rules": {
    "h1-removed": "off",
    "title-removed": "critical",
    "noindex-added": "warn"
  }
}

• ignore — globs (*, **, ?, {a,b}) relative to project root. node_modules, .git, build dirs are always skipped.
• rules — per rule: "critical", "warn" or "off".
• baseUrl — absolute links/sitemap <loc> under this URL are treated as internal.

Invalid JSON falls back to defaults with a warning.

Limits

• Parsing is lenient, not semantic. HTML/Astro/Vue/Svelte/JSX go through htmlparser2; Next/Nuxt metadata and frontmatter use regex on literal values. Computed titles (title: getTitle()) count as "present"; dynamic generateMetadata bodies are only skimmed.
• SEO components are recognised by name (NextSeo, SEO, Seo, Head, Meta, *Head, *Seo, Astro *Layout); title passed via variables counts as present.
• Layout inheritance only looks at files edited in this session (ledger) and resolvable imports/conventional ancestors; it can't see a title set by a layout in another package.
• Route-deletion snapshots walk the project twice per bash call (disable with "snapshotRoutes": false on huge repos). Routes removed after the fact can't be blocked, only reported.
• JSON-LD validity is only judged for literal (non-templated) blocks.
• Redirect parsing for next.config.*/astro.config.*/docusaurus.config.* is regex-based on source: / path / from: keys. SvelteKit hooks.server is only understood for event.url.pathname === '/x' + redirect() and literal redirect maps; arbitrary logic is skipped. nginx/Apache support covers single-line rewrite/Redirect*/RewriteRule … [R] and simple location … { return 30x } blocks (no if, maps or includes).
• Sitemaps generated at build time (next-sitemap, @astrojs/sitemap) can't be checked; /seo-guard says so.
• Bash write detection is best-effort shell parsing: no variable expansion, globs, $(…), or scripts run via python/node that write files themselves (those are only caught if they redirect into a watched file). sed/perl support covers plain s/// substitutions.
• Only checks what the agent does through Pi's edit, write, bash tools; it is not a build-time linter.

Development

npm install
npm test
npm run tsc
pi -e .      # load locally

License

MIT