@djangocfg/seo 2.1.50

package/README.md

@@ -0,0 +1,192 @@
+# @djangocfg/seo
+
+SEO audit toolkit for Next.js App Router. Parallel execution, AI-ready split reports.
+
+**Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
+
+## Two Modes
+
+| Mode | Target | Use Case |
+|------|--------|----------|
+| **Audit** (HTTP) | Live site | Production SEO check, broken links, GSC data |
+| **Content** (files) | `content/` dir | MDX link validation, sitemap generation |
+
+**Audit** — crawls your deployed site via HTTP. Use for production audits.
+
+**Content** — scans local MDX files in `content/` directory. Use for Nextra/docs projects to validate links before deploy and generate `sitemap.ts`.
+
+## Quick Start
+
+```bash
+pnpm add @djangocfg/seo
+
+# Full SEO audit
+djangocfg-seo audit
+
+# Scan app/ routes and compare with sitemap
+djangocfg-seo routes --check
+
+# Check broken links
+djangocfg-seo links
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `audit` | Full audit (robots + sitemap + crawl + links + routes + GSC) |
+| `routes` | Scan app/ directory, compare with sitemap |
+| `crawl` | Crawl site, analyze meta/titles/H1 |
+| `links` | Check for broken links |
+| `robots` | Analyze robots.txt |
+| `sitemap` | Validate sitemap.xml |
+| `inspect` | GSC URL inspection |
+| `content check` | Check MDX links in content/ |
+| `content fix` | Fix absolute → relative links |
+| `content sitemap` | Generate sitemap.ts from content/ |
+
+## Options
+
+```
+--env, -e          prod (default) or dev
+--site, -s         Site URL (overrides env)
+--output, -o       Output directory (default: ./seo-reports)
+--format, -f       split (default), json, markdown, ai-summary, all
+--max-pages        Max pages to crawl (default: 100)
+--service-account  Google service account JSON path
+--app-dir          Path to app/ directory
+--check            Compare routes with sitemap
+--verify           Verify routes are accessible
+```
+
+## Routes Command
+
+Scans Next.js App Router `app/` directory:
+
+```bash
+djangocfg-seo routes           # List all routes
+djangocfg-seo routes --check   # Compare with sitemap
+djangocfg-seo routes --verify  # Verify routes return 200
+```
+
+Output:
+```
+Routes found: 16
+├── Static: 11
+├── Dynamic: 1
+└── API: 4
+
+Sitemap comparison:
+├── Matching: 8
+├── Missing from sitemap: 3
+└── Extra in sitemap: 50
+```
+
+Handles: route groups `(group)`, dynamic `[slug]`, catch-all `[...slug]`, parallel `@folder`, private `_folder`.
+
+## Reports
+
+Default `split` format - AI-optimized files under 1000 lines:
+
+```
+@reports/seo/
+├── CLAUDE.md              # AI context file
+├── seo-*-index.md         # Summary + links to categories
+├── seo-*-technical.md     # Broken links, sitemap, robots.txt
+├── seo-*-content.md       # H1, meta, titles
+├── seo-*-performance.md   # Load time, TTFB
+└── seo-ai-summary-*.md    # Quick overview
+```
+
+## Google Search Console
+
+Auto-detects `gsc-key.json` in project root:
+
+1. Create service account: [console.cloud.google.com](https://console.cloud.google.com/iam-admin/serviceaccounts/create)
+2. Download JSON key as `gsc-key.json`
+3. Enable API: [searchconsole API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)
+4. Add service account email to GSC with Full access
+5. Run audit - GSC data included automatically
+
+## Programmatic Usage
+
+```typescript
+import { SiteCrawler, analyzeCrawlResults } from '@djangocfg/seo/crawler';
+import { checkLinks, linkResultsToSeoIssues } from '@djangocfg/seo/link-checker';
+import { scanRoutes, compareWithSitemap } from '@djangocfg/seo/routes';
+import { generateAndSaveReports } from '@djangocfg/seo/reports';
+
+// Crawl
+const crawler = new SiteCrawler('https://example.com', { maxPages: 100 });
+const results = await crawler.crawl();
+const crawlIssues = analyzeCrawlResults(results);
+
+// Routes
+const routes = scanRoutes({ appDir: './app' });
+console.log(routes.staticRoutes, routes.dynamicRoutes);
+
+// Links
+const linkResult = await checkLinks({ url: 'https://example.com' });
+const linkIssues = linkResultsToSeoIssues(linkResult);
+
+// Reports
+await generateAndSaveReports('https://example.com', {
+  issues: [...crawlIssues, ...linkIssues],
+}, {
+  outputDir: './reports',
+  formats: ['split'],
+});
+```
+
+## Exports
+
+```typescript
+// Main
+import { SiteCrawler, checkLinks, GoogleConsoleClient } from '@djangocfg/seo';
+
+// Submodules
+import { SiteCrawler, analyzeCrawlResults } from '@djangocfg/seo/crawler';
+import { checkLinks, linkResultsToSeoIssues } from '@djangocfg/seo/link-checker';
+import { scanRoutes, compareWithSitemap, verifyRoutes } from '@djangocfg/seo/routes';
+import { GoogleConsoleClient } from '@djangocfg/seo/google-console';
+import { generateAndSaveReports } from '@djangocfg/seo/reports';
+import type { SeoIssue, SeoReport, CrawlResult } from '@djangocfg/seo/types';
+```
+
+## Issue Types
+
+| Severity | Description |
+|----------|-------------|
+| `critical` | Blocks indexing |
+| `error` | SEO problems |
+| `warning` | Recommendations |
+| `info` | Best practices |
+
+| Category | Examples |
+|----------|----------|
+| `technical` | Broken links, sitemap, robots.txt |
+| `content` | Missing H1, meta description |
+| `indexing` | Not indexed, crawl errors |
+| `performance` | Slow load time, high TTFB |
+
+## Architecture
+
+```
+djangocfg-seo audit
+    │
+    ├─ robots.txt → get sitemap URLs
+    │
+    ├─ [PARALLEL] ─┬─ Sitemap
+    │              ├─ Crawl (+ TTFB metrics)
+    │              └─ Links
+    │
+    ├─ Routes (compare with sitemap)
+    │
+    └─ GSC (sc-domain:xxx)
+           │
+           └─ @reports/seo/
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node