@djangocfg/seo 2.1.50

package/src/cli/commands/routes.ts

@@ -0,0 +1,126 @@
+/**
+ * Routes Command - Scan app/ directory
+ */
+
+import consola from 'consola';
+import chalk from 'chalk';
+import { getSiteUrl } from '../../config.js';
+import { analyzeSitemap } from '../../crawler/index.js';
+import { scanRoutes, findAppDir, compareWithSitemap, verifyRoutes, generateRoutesSummary } from '../../routes/index.js';
+import type { CliOptions } from '../types.js';
+
+export async function runRoutes(options: CliOptions) {
+  const siteUrl = getSiteUrl(options);
+  const appDir = options['app-dir'] || findAppDir();
+
+  if (!appDir) {
+    consola.error('Could not find app/ directory. Use --app-dir to specify path.');
+    process.exit(1);
+  }
+
+  console.log('');
+  consola.box(`${chalk.bold('Routes Scanner')}\n${appDir}`);
+
+  // Scan routes
+  consola.start('Scanning app/ directory...');
+  const scanResult = scanRoutes({ appDir });
+
+  consola.success(`Found ${scanResult.routes.length} routes`);
+  console.log(`  ├── Static: ${scanResult.staticRoutes.length}`);
+  console.log(`  ├── Dynamic: ${scanResult.dynamicRoutes.length}`);
+  console.log(`  └── API: ${scanResult.apiRoutes.length}`);
+
+  // Show routes
+  if (scanResult.staticRoutes.length > 0) {
+    console.log('');
+    consola.info('Static routes:');
+    for (const route of scanResult.staticRoutes.slice(0, 20)) {
+      console.log(`  ${chalk.green('→')} ${route.path}`);
+    }
+    if (scanResult.staticRoutes.length > 20) {
+      console.log(`  ${chalk.dim(`... +${scanResult.staticRoutes.length - 20} more`)}`);
+    }
+  }
+
+  if (scanResult.dynamicRoutes.length > 0) {
+    console.log('');
+    consola.info('Dynamic routes:');
+    for (const route of scanResult.dynamicRoutes.slice(0, 10)) {
+      const params = route.dynamicSegments.join(', ');
+      console.log(`  ${chalk.yellow('→')} ${route.path} ${chalk.dim(`[${params}]`)}`);
+    }
+    if (scanResult.dynamicRoutes.length > 10) {
+      console.log(`  ${chalk.dim(`... +${scanResult.dynamicRoutes.length - 10} more`)}`);
+    }
+  }
+
+  // Compare with sitemap (--check flag)
+  if (options.check) {
+    console.log('');
+    consola.start('Loading sitemap...');
+
+    try {
+      const sitemapUrl = new URL('/sitemap.xml', siteUrl).href;
+      const sitemap = await analyzeSitemap(sitemapUrl);
+      const sitemapUrls = sitemap.urls.map(u => u.loc);
+
+      consola.success(`Loaded ${sitemapUrls.length} URLs from sitemap`);
+
+      const comparison = compareWithSitemap(scanResult, sitemapUrls, siteUrl);
+
+      console.log('');
+      consola.info('Sitemap comparison:');
+      console.log(`  ├── Matching: ${comparison.matching.length}`);
+      console.log(`  ├── Missing from sitemap: ${chalk.yellow(String(comparison.missingFromSitemap.length))}`);
+      console.log(`  └── Extra in sitemap: ${comparison.extraInSitemap.length}`);
+
+      if (comparison.missingFromSitemap.length > 0) {
+        console.log('');
+        consola.warn('Routes missing from sitemap:');
+        for (const route of comparison.missingFromSitemap.slice(0, 10)) {
+          console.log(`  ${chalk.red('✗')} ${route.path}`);
+        }
+        if (comparison.missingFromSitemap.length > 10) {
+          console.log(`  ${chalk.dim(`... +${comparison.missingFromSitemap.length - 10} more`)}`);
+        }
+      }
+    } catch (error) {
+      consola.error(`Failed to load sitemap: ${(error as Error).message}`);
+    }
+  }
+
+  // Verify routes (--verify flag)
+  if (options.verify) {
+    console.log('');
+    consola.start('Verifying routes...');
+
+    const verification = await verifyRoutes(scanResult, {
+      baseUrl: siteUrl,
+      timeout: parseInt(options.timeout, 10),
+      concurrency: 5,
+      staticOnly: true,
+    });
+
+    const accessible = verification.filter(r => r.isAccessible);
+    const broken = verification.filter(r => !r.isAccessible);
+
+    consola.success(`Verified ${verification.length} routes`);
+    console.log(`  ├── Accessible: ${chalk.green(String(accessible.length))}`);
+    console.log(`  └── Broken: ${chalk.red(String(broken.length))}`);
+
+    if (broken.length > 0) {
+      console.log('');
+      consola.error('Broken routes:');
+      for (const r of broken.slice(0, 10)) {
+        console.log(`  ${chalk.red('✗')} ${r.route.path} → ${r.statusCode || r.error}`);
+      }
+      if (broken.length > 10) {
+        console.log(`  ${chalk.dim(`... +${broken.length - 10} more`)}`);
+      }
+    }
+  }
+
+  // Summary
+  console.log('');
+  console.log(generateRoutesSummary(scanResult));
+}

package/src/cli/commands/sitemap.ts

@@ -0,0 +1,48 @@
+/**
+ * Sitemap Command - Sitemap validator
+ */
+
+import consola from 'consola';
+import { getSiteUrl } from '../../config.js';
+import { analyzeAllSitemaps } from '../../crawler/index.js';
+import type { CliOptions } from '../types.js';
+
+export async function runSitemap(options: CliOptions) {
+  let sitemapUrl = getSiteUrl(options);
+
+  if (!sitemapUrl.endsWith('.xml')) {
+    sitemapUrl = new URL('/sitemap.xml', sitemapUrl).href;
+  }
+
+  consola.start(`Validating sitemap: ${sitemapUrl}`);
+
+  const analyses = await analyzeAllSitemaps(sitemapUrl);
+
+  let totalUrls = 0;
+  let totalIssues = 0;
+
+  for (const analysis of analyses) {
+    if (analysis.exists) {
+      consola.success(`${analysis.url}`);
+      consola.info(`  Type: ${analysis.type}`);
+
+      if (analysis.type === 'sitemap') {
+        consola.info(`  URLs: ${analysis.urls.length}`);
+        totalUrls += analysis.urls.length;
+      } else {
+        consola.info(`  Child sitemaps: ${analysis.childSitemaps.length}`);
+      }
+
+      if (analysis.issues.length > 0) {
+        totalIssues += analysis.issues.length;
+        for (const issue of analysis.issues) {
+          consola.warn(`  [${issue.severity}] ${issue.title}`);
+        }
+      }
+    } else {
+      consola.error(`${analysis.url} - Not found`);
+    }
+  }
+
+  consola.box(`Total URLs: ${totalUrls}\nTotal Issues: ${totalIssues}`);
+}

package/src/cli/index.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * @djangocfg/seo - CLI Tool
+ */
+
+import { parseArgs } from 'node:util';
+import consola from 'consola';
+import chalk from 'chalk';
+import { loadEnvFiles } from '../config.js';
+import { runAudit, runRoutes, runInspect, runCrawl, runLinks, runRobots, runSitemap, runContent } from './commands/index.js';
+import type { CliOptions } from './types.js';
+
+loadEnvFiles();
+
+const VERSION = '1.0.0';
+
+const HELP = `
+${chalk.bold('@djangocfg/seo')} - SEO Analysis Tool v${VERSION}
+
+${chalk.bold('Usage:')}
+  djangocfg-seo <command> [options]
+
+${chalk.bold('Commands:')}
+  audit      Full SEO audit (robots + sitemap + crawl + links)
+  routes     Scan app/ directory and compare with sitemap
+  content    MDX content tools (check, fix, sitemap)
+  crawl      Crawl site and analyze SEO issues
+  links      Check all links for broken links
+  robots     Analyze robots.txt
+  sitemap    Validate sitemap
+  inspect    Inspect URLs via Google Search Console API
+
+${chalk.bold('Options:')}
+  --env, -e          Environment: prod (default) or dev
+  --site, -s         Site URL (overrides env detection)
+  --output, -o       Output directory for reports
+  --format, -f       Report format: split (default), json, markdown, ai-summary, all
+  --max-pages        Maximum pages to crawl (default: 100)
+  --max-depth        Maximum crawl depth (default: 3)
+  --timeout          Request timeout in ms (default: 60000)
+  --concurrency      Max concurrent requests (default: 50)
+  --service-account  Path to Google service account JSON
+  --app-dir          Path to app/ directory (for routes command)
+  --content-dir      Path to content/ directory (for content command)
+  --base-path        Base URL path for docs (default: /docs)
+  --check            Compare routes with sitemap
+  --verify           Verify routes are accessible
+  --fix              Apply fixes (for content fix command)
+  --help, -h         Show this help
+  --version, -v      Show version
+
+${chalk.bold('Examples:')}
+  ${chalk.dim('# Full SEO audit')}
+  djangocfg-seo audit
+
+  ${chalk.dim('# Scan app routes and compare with sitemap')}
+  djangocfg-seo routes --check
+
+  ${chalk.dim('# Check links on production')}
+  djangocfg-seo links
+
+  ${chalk.dim('# Check MDX content links')}
+  djangocfg-seo content check
+
+  ${chalk.dim('# Fix absolute links to relative')}
+  djangocfg-seo content fix --fix
+
+  ${chalk.dim('# Generate sitemap.ts from content')}
+  djangocfg-seo content sitemap
+`;
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      env: { type: 'string', short: 'e', default: 'prod' },
+      site: { type: 'string', short: 's' },
+      output: { type: 'string', short: 'o', default: './seo-reports' },
+      urls: { type: 'string', short: 'u' },
+      'max-pages': { type: 'string', default: '100' },
+      'max-depth': { type: 'string', default: '3' },
+      timeout: { type: 'string', default: '60000' },
+      concurrency: { type: 'string', default: '50' },
+      format: { type: 'string', short: 'f', default: 'split' },
+      'service-account': { type: 'string' },
+      'app-dir': { type: 'string' },
+      'content-dir': { type: 'string' },
+      'base-path': { type: 'string' },
+      check: { type: 'boolean' },
+      verify: { type: 'boolean' },
+      fix: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+    },
+  });
+
+  if (values.version) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  if (values.help || positionals.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  const command = positionals[0];
+  const options = { ...values, _: positionals } as unknown as CliOptions;
+
+  try {
+    switch (command) {
+      case 'audit':
+      case 'report':
+        await runAudit(options);
+        break;
+      case 'routes':
+        await runRoutes(options);
+        break;
+      case 'inspect':
+        await runInspect(options);
+        break;
+      case 'crawl':
+        await runCrawl(options);
+        break;
+      case 'links':
+        await runLinks(options);
+        break;
+      case 'robots':
+        await runRobots(options);
+        break;
+      case 'sitemap':
+        await runSitemap(options);
+        break;
+      case 'content':
+        await runContent(options);
+        break;
+      default:
+        consola.error(`Unknown command: ${command}`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (error) {
+    consola.error(error);
+    process.exit(1);
+  }
+}
+
+main().catch(consola.error);

package/src/cli/types.ts

@@ -0,0 +1,40 @@
+/**
+ * CLI Types and Options
+ */
+
+export interface CliOptions {
+  env: string;
+  site?: string;
+  output: string;
+  urls?: string;
+  'max-pages': string;
+  'max-depth': string;
+  timeout: string;
+  concurrency: string;
+  format: string;
+  'service-account'?: string;
+  'app-dir'?: string;
+  'content-dir'?: string;
+  'base-path'?: string;
+  check?: boolean;
+  verify?: boolean;
+  fix?: boolean;
+  help?: boolean;
+  version?: boolean;
+  /** Positional arguments */
+  _?: string[];
+}
+
+export type ReportFormat = 'json' | 'markdown' | 'ai-summary' | 'split';
+
+export function parseFormats(format: string): ReportFormat[] {
+  if (format === 'all') {
+    return ['json', 'markdown', 'ai-summary', 'split'];
+  }
+
+  if (format === 'split') {
+    return ['ai-summary', 'split'];
+  }
+
+  return format.split(',').map((f) => f.trim()) as ReportFormat[];
+}

package/src/config.ts

@@ -0,0 +1,207 @@
+/**
+ * @djangocfg/seo - Configuration
+ * Environment detection and URL management
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import consola from 'consola';
+import chalk from 'chalk';
+
+export interface EnvConfig {
+  prod: string | undefined;
+  dev: string | undefined;
+}
+
+export interface SeoConfig {
+  env: EnvConfig;
+  cwd: string;
+}
+
+const config: SeoConfig = {
+  env: {
+    prod: undefined,
+    dev: undefined,
+  },
+  cwd: process.cwd(),
+};
+
+/**
+ * Parse a .env file and return key-value pairs
+ */
+export function parseEnvFile(filePath: string): Record<string, string> {
+  const content = readFileSync(filePath, 'utf-8');
+  const vars: Record<string, string> = {};
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    let value = trimmed.slice(eqIndex + 1).trim();
+
+    // Remove quotes
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    vars[key] = value;
+  }
+
+  return vars;
+}
+
+/**
+ * Load .env files from the current working directory
+ */
+export function loadEnvFiles(cwd?: string): EnvConfig {
+  const workDir = cwd || process.cwd();
+  config.cwd = workDir;
+
+  // Load .env.production
+  const prodEnvPath = resolve(workDir, '.env.production');
+  if (existsSync(prodEnvPath)) {
+    const vars = parseEnvFile(prodEnvPath);
+    config.env.prod = vars.NEXT_PUBLIC_SITE_URL || vars.SITE_URL;
+  }
+
+  // Load .env.development
+  const devEnvPath = resolve(workDir, '.env.development');
+  if (existsSync(devEnvPath)) {
+    const vars = parseEnvFile(devEnvPath);
+    config.env.dev = vars.NEXT_PUBLIC_SITE_URL || vars.SITE_URL;
+  }
+
+  // Fallback to .env.local or .env
+  if (!config.env.prod && !config.env.dev) {
+    for (const envFile of ['.env.local', '.env']) {
+      const envPath = resolve(workDir, envFile);
+      if (existsSync(envPath)) {
+        const vars = parseEnvFile(envPath);
+        const url = vars.NEXT_PUBLIC_SITE_URL || vars.SITE_URL;
+        if (url) {
+          config.env.prod = url;
+          break;
+        }
+      }
+    }
+  }
+
+  return config.env;
+}
+
+/**
+ * Get the loaded environment configuration
+ */
+export function getEnvConfig(): EnvConfig {
+  return config.env;
+}
+
+/**
+ * Get site URL based on options and environment
+ */
+export function getSiteUrl(options: {
+  site?: string;
+  env?: string;
+}): string {
+  // Explicit --site flag takes priority
+  if (options.site) {
+    return options.site;
+  }
+
+  // Use --env flag or default to 'prod'
+  const env = options.env || 'prod';
+  const isProd = env === 'prod' || env === 'production';
+
+  // Get URL from loaded env files
+  const url = isProd ? config.env.prod : config.env.dev;
+
+  if (url) {
+    const envLabel = isProd ? 'production' : 'development';
+    consola.info(`Using ${chalk.cyan(envLabel)} URL: ${chalk.bold(url)}`);
+    return url;
+  }
+
+  // Fallback to process.env (already loaded or from shell)
+  const fallbackUrl =
+    process.env.NEXT_PUBLIC_SITE_URL ||
+    process.env.SITE_URL ||
+    process.env.BASE_URL;
+
+  if (fallbackUrl) {
+    consola.info(`Using URL from environment: ${fallbackUrl}`);
+    return fallbackUrl;
+  }
+
+  // Show available options if no URL found
+  console.log('');
+  consola.error('No site URL found!');
+  console.log('');
+  if (config.env.prod || config.env.dev) {
+    consola.info('Available environments:');
+    if (config.env.prod) consola.log(`  ${chalk.green('prod')}: ${config.env.prod}`);
+    if (config.env.dev) consola.log(`  ${chalk.yellow('dev')}:  ${config.env.dev}`);
+    console.log('');
+    consola.info(`Use ${chalk.cyan('--env prod')} or ${chalk.cyan('--env dev')} to select`);
+  } else {
+    consola.info('Create .env.production or .env.development with NEXT_PUBLIC_SITE_URL');
+    consola.info('Or use --site https://example.com');
+  }
+  process.exit(1);
+}
+
+/**
+ * Print detected environment info
+ */
+export function printEnvInfo(): void {
+  console.log('');
+  consola.info('Environment configuration:');
+  if (config.env.prod) {
+    consola.log(`  ${chalk.green('prod')}: ${config.env.prod}`);
+  }
+  if (config.env.dev) {
+    consola.log(`  ${chalk.yellow('dev')}:  ${config.env.dev}`);
+  }
+  if (!config.env.prod && !config.env.dev) {
+    consola.warn('  No .env files found');
+  }
+}
+
+/** Default Google service account key filename */
+const GSC_KEY_FILENAME = 'gsc-key.json';
+
+/**
+ * Find Google service account key file
+ * Searches in current directory for gsc-key.json
+ */
+export function findGoogleServiceAccount(explicitPath?: string): string | undefined {
+  // Explicit path takes priority
+  if (explicitPath) {
+    const resolved = resolve(config.cwd, explicitPath);
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+    consola.warn(`Service account file not found: ${explicitPath}`);
+    return undefined;
+  }
+
+  // Auto-detect in current directory
+  const defaultPath = resolve(config.cwd, GSC_KEY_FILENAME);
+  if (existsSync(defaultPath)) {
+    consola.info(`Found Google service account: ${chalk.cyan(GSC_KEY_FILENAME)}`);
+    return defaultPath;
+  }
+
+  return undefined;
+}
+
+/**
+ * Get Google service account key filename for hints
+ */
+export function getGscKeyFilename(): string {
+  return GSC_KEY_FILENAME;
+}

package/src/content/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Content module for MDX/Nextra projects
+ * Provides tools for checking links, fixing relative links, and generating sitemaps
+ */
+
+// Types
+export type {
+  ContentConfig,
+  SitemapConfig,
+  SitemapItem,
+  SitemapData,
+  FileInfo,
+  LinkType,
+  ExtractedLink,
+  BrokenLink,
+  LinkCheckResult,
+  LinkFix,
+  LinkFixResult,
+  FixLinksResult,
+  ContentScanResult,
+} from './types.js';
+
+export { DEFAULT_CONFIG, DEFAULT_SITEMAP_CONFIG } from './types.js';
+
+// Scanner
+export {
+  detectProjectType,
+  hasMetaFiles,
+  scanProject,
+  getAllFiles,
+  getAllMdxFiles,
+  getPageFiles,
+  getFileInfo,
+  pathExists,
+  findContentDir,
+  findAppDir,
+} from './scanner.js';
+
+// Link checker
+export { checkContentLinks, groupBrokenLinksByFile } from './link-checker.js';
+
+// Link fixer
+export { fixContentLinks } from './link-fixer.js';
+
+// Sitemap generator
+export {
+  generateSitemapData,
+  generateSitemap,
+  flattenSitemap,
+  countSitemapItems,
+} from './sitemap-generator.js';