@djangocfg/seo 2.1.50

package/src/cli/commands/audit.ts

@@ -0,0 +1,260 @@
+/**
+ * Audit Command - Full SEO audit
+ */
+
+import consola from 'consola';
+import chalk from 'chalk';
+import { getSiteUrl, findGoogleServiceAccount, getGscKeyFilename } from '../../config.js';
+import { GoogleConsoleClient, analyzeInspectionResults } from '../../google-console/index.js';
+import { SiteCrawler, analyzeCrawlResults, analyzeRobotsTxt, analyzeAllSitemaps, analyzeSitemap } from '../../crawler/index.js';
+import { checkLinks, linkResultsToSeoIssues } from '../../link-checker/index.js';
+import { generateAndSaveReports, printReportSummary } from '../../reports/index.js';
+import { scanRoutes, findAppDir, compareWithSitemap, analyzeRoutes } from '../../routes/index.js';
+import type { SeoIssue, UrlInspectionResult, CrawlResult } from '../../types/index.js';
+import { parseFormats, type CliOptions } from '../types.js';
+
+interface StepResult {
+  name: string;
+  issues: SeoIssue[];
+  meta?: Record<string, any>;
+  error?: string;
+}
+
+export async function runAudit(options: CliOptions) {
+  const siteUrl = getSiteUrl(options);
+  const startTime = Date.now();
+
+  console.log('');
+  consola.box(`${chalk.bold('SEO Audit')}\n${siteUrl}`);
+
+  // Auto-detect or use explicit service account
+  const serviceAccountPath = findGoogleServiceAccount(options['service-account']);
+  const hasGsc = !!serviceAccountPath;
+
+  // Auto-detect app directory for routes
+  const appDir = options['app-dir'] || findAppDir();
+  const hasRoutes = !!appDir;
+
+  // Show hints
+  if (!serviceAccountPath) {
+    const keyFile = getGscKeyFilename();
+    console.log('');
+    consola.info(chalk.dim('GSC not configured. Save service account as ' + chalk.cyan(keyFile) + ' for indexing data.'));
+  }
+
+  const allIssues: SeoIssue[] = [];
+  const allInspections: UrlInspectionResult[] = [];
+  const allCrawlResults: CrawlResult[] = [];
+  const results: StepResult[] = [];
+  let collectedSitemapUrls: string[] = [];
+
+  // Progress tracking: robots + sitemap + crawl + links + (routes?) + (gsc?)
+  let totalSteps = 4;
+  if (hasRoutes) totalSteps++;
+  if (hasGsc) totalSteps++;
+  let completedSteps = 0;
+  const errors: string[] = [];
+
+  const updateProgress = (step: string, status: 'running' | 'done' | 'error') => {
+    const bar = '█'.repeat(completedSteps) + '░'.repeat(totalSteps - completedSteps);
+    const pct = Math.round((completedSteps / totalSteps) * 100);
+    if (status === 'running') {
+      process.stdout.write(`\r${chalk.cyan('▸')} ${bar} ${pct}% ${chalk.dim(step)}`);
+    } else if (status === 'done') {
+      completedSteps++;
+      const newBar = '█'.repeat(completedSteps) + '░'.repeat(totalSteps - completedSteps);
+      const newPct = Math.round((completedSteps / totalSteps) * 100);
+      process.stdout.write(`\r${chalk.green('✓')} ${newBar} ${newPct}% ${chalk.dim(step)}${' '.repeat(20)}\n`);
+    } else {
+      process.stdout.write(`\r${chalk.red('✗')} ${bar} ${pct}% ${chalk.dim(step)}${' '.repeat(20)}\n`);
+    }
+  };
+
+  // Phase 1: robots.txt (needed for sitemap URLs)
+  console.log('');
+  let sitemapUrls: string[] = [];
+  updateProgress('robots.txt', 'running');
+  try {
+    const analysis = await analyzeRobotsTxt(siteUrl);
+    sitemapUrls = analysis.sitemaps;
+    results.push({ name: 'robots.txt', issues: analysis.issues, meta: { exists: analysis.exists } });
+    allIssues.push(...analysis.issues);
+    updateProgress('robots.txt', 'done');
+  } catch (e) {
+    errors.push(`robots.txt: ${(e as Error).message}`);
+    updateProgress('robots.txt', 'error');
+  }
+
+  // Phase 2: Parallel execution (Sitemap + Crawl + Links)
+  const parallelTasks = await Promise.allSettled([
+    // Sitemap
+    (async () => {
+      updateProgress('Sitemap', 'running');
+      const issues: SeoIssue[] = [];
+      const sitemapsToCheck = sitemapUrls.length > 0
+        ? sitemapUrls
+        : [new URL('/sitemap.xml', siteUrl).href];
+
+      let totalUrls = 0;
+      for (const smUrl of sitemapsToCheck) {
+        const analyses = await analyzeAllSitemaps(smUrl);
+        for (const a of analyses) {
+          issues.push(...a.issues);
+          totalUrls += a.urls.length;
+          // Collect URLs for routes comparison
+          collectedSitemapUrls.push(...a.urls.map(u => u.loc));
+        }
+      }
+      updateProgress('Sitemap', 'done');
+      return { name: 'Sitemap', issues, meta: { urls: totalUrls } };
+    })(),
+
+    // Crawl
+    (async () => {
+      updateProgress('Crawl', 'running');
+      const crawler = new SiteCrawler(siteUrl, {
+        maxPages: parseInt(options['max-pages'], 10),
+        maxDepth: parseInt(options['max-depth'], 10),
+      });
+      const crawlResults = await crawler.crawl();
+      allCrawlResults.push(...crawlResults);
+      const issues = analyzeCrawlResults(crawlResults);
+      updateProgress('Crawl', 'done');
+      return { name: 'Crawl', issues, meta: { pages: crawlResults.length } };
+    })(),
+
+    // Links
+    (async () => {
+      updateProgress('Links', 'running');
+      const result = await checkLinks({
+        url: siteUrl,
+        timeout: parseInt(options.timeout, 10),
+        concurrency: parseInt(options.concurrency, 10),
+        verbose: false,
+      });
+      const issues = linkResultsToSeoIssues(result);
+      updateProgress('Links', 'done');
+      return { name: 'Links', issues, meta: { total: result.total, broken: result.broken } };
+    })(),
+  ]);
+
+  // Collect parallel results
+  for (const task of parallelTasks) {
+    if (task.status === 'fulfilled') {
+      results.push(task.value);
+      allIssues.push(...task.value.issues);
+    } else {
+      errors.push(task.reason?.message || 'Unknown error');
+    }
+  }
+
+  // Phase 3: Routes (needs sitemap URLs from parallel phase)
+  if (hasRoutes && appDir) {
+    updateProgress('Routes', 'running');
+    try {
+      const scanResult = scanRoutes({ appDir });
+      const comparison = compareWithSitemap(scanResult, collectedSitemapUrls, siteUrl);
+      const issues = analyzeRoutes(scanResult, comparison);
+
+      results.push({
+        name: 'Routes',
+        issues,
+        meta: {
+          static: scanResult.staticRoutes.length,
+          dynamic: scanResult.dynamicRoutes.length,
+          missing: comparison.missingFromSitemap.length,
+        },
+      });
+      allIssues.push(...issues);
+      updateProgress('Routes', 'done');
+    } catch (e) {
+      errors.push(`Routes: ${(e as Error).message}`);
+      updateProgress('Routes', 'error');
+    }
+  }
+
+  // Phase 4: GSC (needs crawl results)
+  if (hasGsc) {
+    updateProgress('GSC', 'running');
+    try {
+      const client = new GoogleConsoleClient({
+        siteUrl,
+        serviceAccountPath,
+      });
+
+      const isAuth = await client.verify();
+      if (isAuth) {
+        const urlsToInspect = allCrawlResults
+          .filter((r) => r.statusCode === 200)
+          .slice(0, 50)
+          .map((r) => r.url);
+
+        const inspections = await client.inspectUrls(urlsToInspect);
+        allInspections.push(...inspections);
+        const issues = analyzeInspectionResults(inspections);
+        results.push({ name: 'GSC', issues, meta: { inspected: inspections.length } });
+        allIssues.push(...issues);
+      } else {
+        results.push({ name: 'GSC', issues: [], meta: { skipped: true } });
+      }
+      updateProgress('GSC', 'done');
+    } catch (e) {
+      errors.push(`GSC: ${(e as Error).message}`);
+      updateProgress('GSC', 'error');
+    }
+  }
+
+  // Show errors if any
+  if (errors.length > 0) {
+    console.log('');
+    for (const err of errors) {
+      consola.error(err);
+    }
+  }
+
+  // Summary table
+  console.log('');
+  consola.log(chalk.bold('Results:'));
+  for (const r of results) {
+    const issueStr = r.issues.length > 0 ? chalk.yellow(`${r.issues.length} issues`) : chalk.green('OK');
+    const metaStr = r.meta ? chalk.dim(` (${Object.entries(r.meta).map(([k, v]) => `${k}: ${v}`).join(', ')})`) : '';
+    consola.log(`  ${r.name}: ${issueStr}${metaStr}`);
+  }
+
+  // Generate reports
+  console.log('');
+  consola.start('Generating reports...');
+
+  const formats = parseFormats(options.format);
+  const { report, files } = await generateAndSaveReports(
+    siteUrl,
+    {
+      issues: allIssues,
+      urlInspections: allInspections,
+      crawlResults: allCrawlResults,
+    },
+    {
+      outputDir: options.output,
+      formats,
+      includeRawData: true,
+    }
+  );
+
+  // Summary
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+  console.log('');
+  printReportSummary(report);
+
+  console.log('');
+  consola.info(`Reports saved to: ${chalk.cyan(options.output)}`);
+  if (files.json) consola.log(`  ${chalk.dim('→')} ${files.json}`);
+  if (files.markdown) consola.log(`  ${chalk.dim('→')} ${files.markdown}`);
+  if (files.aiSummary) consola.log(`  ${chalk.dim('→')} ${files.aiSummary}`);
+  if (files.split) {
+    consola.log(`  ${chalk.dim('→')} ${files.split.index} ${chalk.dim('(index)')}`);
+    consola.log(`  ${chalk.dim('→')} ${files.split.categories.length} category files`);
+  }
+
+  console.log('');
+  consola.success(`Audit completed in ${duration}s`);
+}

package/src/cli/commands/content.ts

@@ -0,0 +1,180 @@
+/**
+ * Content Command - MDX/Nextra content tools
+ * Subcommands: check, fix, sitemap
+ */
+
+import consola from 'consola';
+import chalk from 'chalk';
+import path from 'path';
+import {
+  checkContentLinks,
+  groupBrokenLinksByFile,
+  fixContentLinks,
+  generateSitemap,
+  countSitemapItems,
+  detectProjectType,
+  findContentDir,
+} from '../../content/index.js';
+import type { CliOptions } from '../types.js';
+
+const CONTENT_HELP = `
+${chalk.bold('Content Commands')} - MDX/Nextra content tools
+
+${chalk.bold('Usage:')}
+  djangocfg-seo content <subcommand> [options]
+
+${chalk.bold('Subcommands:')}
+  check     Check links in content/ directory
+  fix       Fix absolute links to relative
+  sitemap   Generate sitemap.ts from content/
+
+${chalk.bold('Options:')}
+  --content-dir <path>  Content directory (default: content/)
+  --output <path>       Output file for sitemap (default: app/_core/sitemap.ts)
+  --fix                 Apply fixes (for 'fix' subcommand)
+  --base-path <path>    Base URL path (default: /docs)
+
+${chalk.bold('Examples:')}
+  djangocfg-seo content check
+  djangocfg-seo content fix --fix
+  djangocfg-seo content sitemap --output app/_core/sitemap.ts
+`;
+
+export async function runContent(options: CliOptions) {
+  const subcommand = options._[1]; // content <subcommand>
+
+  if (!subcommand || subcommand === 'help') {
+    console.log(CONTENT_HELP);
+    return;
+  }
+
+  const cwd = process.cwd();
+  const contentDir = options['content-dir']
+    ? path.resolve(cwd, options['content-dir'])
+    : findContentDir(cwd);
+
+  if (!contentDir && subcommand !== 'sitemap') {
+    consola.error('Could not find content/ directory. Use --content-dir to specify path.');
+    process.exit(1);
+  }
+
+  // Detect project type
+  const projectType = detectProjectType(cwd);
+  console.log('');
+  consola.box(`${chalk.bold('Content Tools')}\nProject: ${projectType}\nPath: ${contentDir || cwd}`);
+
+  switch (subcommand) {
+    case 'check':
+      await runCheck(contentDir!, options);
+      break;
+    case 'fix':
+      await runFix(contentDir!, options);
+      break;
+    case 'sitemap':
+      await runSitemapGenerate(cwd, options);
+      break;
+    default:
+      consola.error(`Unknown subcommand: ${subcommand}`);
+      console.log(CONTENT_HELP);
+      process.exit(1);
+  }
+}
+
+/**
+ * Check links in content directory
+ */
+async function runCheck(contentDir: string, options: CliOptions) {
+  consola.start('Checking links in content/ folder...');
+
+  const basePath = options['base-path'] || '/docs';
+  const result = checkContentLinks(contentDir, { basePath });
+
+  if (result.success) {
+    console.log('');
+    consola.success('All links are valid!');
+    console.log(`  Checked ${result.filesChecked} files, ${result.uniqueLinks} unique links.`);
+    return;
+  }
+
+  console.log('');
+  consola.error(`Found ${result.brokenLinks.length} broken links:`);
+  console.log('');
+
+  const byFile = groupBrokenLinksByFile(result.brokenLinks);
+
+  for (const [file, links] of byFile) {
+    console.log(`${chalk.cyan('📄')} ${file}`);
+    for (const link of links) {
+      console.log(`   L${link.line}: ${chalk.red('✗')} ${link.link} ${chalk.dim(`(${link.type}: "${link.raw}")`)}`);
+    }
+    console.log('');
+  }
+
+  console.log(`${chalk.bold('Summary:')} ${result.brokenLinks.length} broken links in ${byFile.size} files`);
+  console.log(`   Checked ${result.filesChecked} files, ${result.uniqueLinks} unique links.`);
+
+  process.exit(1);
+}
+
+/**
+ * Fix absolute links to relative
+ */
+async function runFix(contentDir: string, options: CliOptions) {
+  const applyFixes = options.fix === true;
+
+  consola.start(applyFixes ? 'Fixing links...' : 'Checking for absolute links that can be relative...');
+
+  const result = fixContentLinks(contentDir, { apply: applyFixes });
+
+  if (result.totalChanges === 0) {
+    console.log('');
+    consola.success('No absolute links that can be converted to relative.');
+    return;
+  }
+
+  console.log('');
+  console.log(`Found ${result.totalChanges} links that can be relative:`);
+  console.log('');
+
+  for (const { file, fixes } of result.fileChanges) {
+    console.log(`${chalk.cyan('📄')} ${file}`);
+    for (const { from, to, line } of fixes) {
+      console.log(`   L${line}: ${from} ${chalk.yellow('→')} ${to}`);
+    }
+    console.log('');
+  }
+
+  if (applyFixes) {
+    consola.success(`Fixed ${result.totalChanges} links in ${result.fileChanges.length} files.`);
+  } else {
+    console.log(`${chalk.yellow('💡')} Run with --fix to apply changes:`);
+    console.log(`   djangocfg-seo content fix --fix`);
+  }
+}
+
+/**
+ * Generate sitemap.ts
+ */
+async function runSitemapGenerate(cwd: string, options: CliOptions) {
+  consola.start('Generating sitemap...');
+
+  // Use specific sitemap output, not the report output directory
+  // Check if output ends with .ts (sitemap file) or use default
+  const rawOutput = options.output;
+  const output = rawOutput?.endsWith('.ts') ? rawOutput : 'app/_core/sitemap.ts';
+  const contentDir = options['content-dir'] || 'content';
+  const basePath = options['base-path'] || '/docs';
+
+  const { outputPath, data } = await generateSitemap(cwd, {
+    output,
+    config: { contentDir, basePath },
+  });
+
+  const counts = countSitemapItems(data);
+
+  console.log('');
+  consola.success(`Sitemap generated at ${outputPath}`);
+  console.log(`  ├── App pages: ${counts.app}`);
+  console.log(`  ├── Doc pages: ${counts.docs}`);
+  console.log(`  └── Total: ${counts.total}`);
+}

package/src/cli/commands/crawl.ts

@@ -0,0 +1,32 @@
+/**
+ * Crawl Command - Site crawler
+ */
+
+import consola from 'consola';
+import { getSiteUrl } from '../../config.js';
+import { SiteCrawler, analyzeCrawlResults } from '../../crawler/index.js';
+import { generateAndSaveReports } from '../../reports/index.js';
+import { parseFormats, type CliOptions } from '../types.js';
+
+export async function runCrawl(options: CliOptions) {
+  const siteUrl = getSiteUrl(options);
+
+  consola.start(`Starting crawl of ${siteUrl}`);
+
+  const crawler = new SiteCrawler(siteUrl, {
+    maxPages: parseInt(options['max-pages'], 10),
+    maxDepth: parseInt(options['max-depth'], 10),
+  });
+
+  const crawlResults = await crawler.crawl();
+  const issues = analyzeCrawlResults(crawlResults);
+
+  consola.info(`Found ${issues.length} issues from ${crawlResults.length} pages`);
+
+  const formats = parseFormats(options.format);
+  await generateAndSaveReports(siteUrl, { issues, crawlResults }, {
+    outputDir: options.output,
+    formats,
+    includeRawData: true,
+  });
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI Commands
+ */
+
+export { runAudit } from './audit.js';
+export { runRoutes } from './routes.js';
+export { runInspect } from './inspect.js';
+export { runCrawl } from './crawl.js';
+export { runLinks } from './links.js';
+export { runRobots } from './robots.js';
+export { runSitemap } from './sitemap.js';
+export { runContent } from './content.js';

package/src/cli/commands/inspect.ts

@@ -0,0 +1,60 @@
+/**
+ * Inspect Command - GSC URL inspection
+ */
+
+import consola from 'consola';
+import { getSiteUrl } from '../../config.js';
+import { GoogleConsoleClient, analyzeInspectionResults } from '../../google-console/index.js';
+import { generateAndSaveReports } from '../../reports/index.js';
+import { loadUrlsFromFile } from '../../utils/index.js';
+import { parseFormats, type CliOptions } from '../types.js';
+
+export async function runInspect(options: CliOptions) {
+  const siteUrl = getSiteUrl(options);
+
+  consola.start('Starting URL inspection via Google Search Console');
+
+  const client = new GoogleConsoleClient({
+    siteUrl,
+    serviceAccountPath: options['service-account'],
+  });
+
+  const isAuth = await client.verify();
+  if (!isAuth) {
+    consola.error('Failed to authenticate with Google Search Console');
+    process.exit(1);
+  }
+
+  let urls: string[];
+
+  if (options.urls) {
+    urls = loadUrlsFromFile(options.urls);
+    consola.info(`Loaded ${urls.length} URLs from ${options.urls}`);
+  } else {
+    consola.info('Fetching URLs from search analytics...');
+    const today = new Date();
+    const startDate = new Date(today.getTime() - 30 * 24 * 60 * 60 * 1000);
+
+    const rows = await client.getSearchAnalytics({
+      startDate: startDate.toISOString().split('T')[0] as string,
+      endDate: today.toISOString().split('T')[0] as string,
+      dimensions: ['page'],
+      rowLimit: 100,
+    });
+
+    urls = rows.map((row) => row.keys?.[0] || '').filter(Boolean);
+    consola.info(`Found ${urls.length} URLs from search analytics`);
+  }
+
+  const results = await client.inspectUrls(urls);
+  const issues = analyzeInspectionResults(results);
+
+  consola.info(`Found ${issues.length} issues`);
+
+  const formats = parseFormats(options.format);
+  await generateAndSaveReports(siteUrl, { issues, urlInspections: results }, {
+    outputDir: options.output,
+    formats,
+    includeRawData: true,
+  });
+}

package/src/cli/commands/links.ts

@@ -0,0 +1,41 @@
+/**
+ * Links Command - Broken link checker
+ */
+
+import consola from 'consola';
+import { getSiteUrl } from '../../config.js';
+import { checkLinks, linkResultsToSeoIssues } from '../../link-checker/index.js';
+import { generateAndSaveReports } from '../../reports/index.js';
+import { parseFormats, type CliOptions } from '../types.js';
+
+export async function runLinks(options: CliOptions) {
+  const siteUrl = getSiteUrl(options);
+
+  consola.start(`Checking links on ${siteUrl}`);
+
+  const result = await checkLinks({
+    url: siteUrl,
+    timeout: parseInt(options.timeout, 10),
+    concurrency: parseInt(options.concurrency, 10),
+    verbose: true,
+  });
+
+  if (result.success) {
+    consola.success(`All ${result.total} links are valid!`);
+  } else {
+    consola.error(`Found ${result.broken} broken links out of ${result.total}`);
+
+    // Generate report if output specified
+    if (options.output !== './seo-reports' || result.broken > 0) {
+      const issues = linkResultsToSeoIssues(result);
+      const formats = parseFormats(options.format);
+      await generateAndSaveReports(siteUrl, { issues }, {
+        outputDir: options.output,
+        formats,
+        includeRawData: false,
+      });
+    }
+  }
+
+  process.exit(result.success ? 0 : 1);
+}

package/src/cli/commands/robots.ts

@@ -0,0 +1,36 @@
+/**
+ * Robots Command - robots.txt analyzer
+ */
+
+import consola from 'consola';
+import { getSiteUrl } from '../../config.js';
+import { analyzeRobotsTxt } from '../../crawler/index.js';
+import type { CliOptions } from '../types.js';
+
+export async function runRobots(options: CliOptions) {
+  const siteUrl = getSiteUrl(options);
+
+  consola.start(`Analyzing robots.txt for ${siteUrl}`);
+
+  const analysis = await analyzeRobotsTxt(siteUrl);
+
+  if (analysis.exists) {
+    consola.success('robots.txt found');
+    consola.info(`Sitemaps: ${analysis.sitemaps.length}`);
+    consola.info(`Disallow rules: ${analysis.disallowedPaths.length}`);
+    consola.info(`Allow rules: ${analysis.allowedPaths.length}`);
+
+    if (analysis.crawlDelay) {
+      consola.info(`Crawl-delay: ${analysis.crawlDelay}`);
+    }
+
+    if (analysis.issues.length > 0) {
+      consola.warn(`Issues found: ${analysis.issues.length}`);
+      for (const issue of analysis.issues) {
+        consola.log(`  - [${issue.severity}] ${issue.title}`);
+      }
+    }
+  } else {
+    consola.warn('robots.txt not found');
+  }
+}