@rankcli/agent-runtime 0.0.1

package/src/tracking/google-analytics.ts

@@ -0,0 +1,265 @@
+// Google Analytics 4 Integration
+// Auto-inject GA4 tracking code into web projects
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface GA4Config {
+  measurementId: string; // G-XXXXXXXXXX
+}
+
+export interface InjectionResult {
+  success: boolean;
+  file?: string;
+  message: string;
+  code?: string;
+}
+
+/**
+ * Generate GA4 tracking script
+ */
+export function generateGA4Script(config: GA4Config): string {
+  return `<!-- Google Analytics 4 -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=${config.measurementId}"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', '${config.measurementId}');
+</script>`;
+}
+
+/**
+ * Generate GA4 for React/Next.js (component-based)
+ */
+export function generateGA4ReactComponent(config: GA4Config): string {
+  return `// components/GoogleAnalytics.tsx
+import Script from 'next/script';
+
+export function GoogleAnalytics() {
+  const measurementId = '${config.measurementId}';
+
+  return (
+    <>
+      <Script
+        src={\`https://www.googletagmanager.com/gtag/js?id=\${measurementId}\`}
+        strategy="afterInteractive"
+      />
+      <Script id="google-analytics" strategy="afterInteractive">
+        {\`
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){dataLayer.push(arguments);}
+          gtag('js', new Date());
+          gtag('config', '\${measurementId}');
+        \`}
+      </Script>
+    </>
+  );
+}`;
+}
+
+/**
+ * Generate GA4 for Vite/vanilla (index.html injection)
+ */
+export function generateGA4ViteScript(config: GA4Config): string {
+  return `    <!-- Google Analytics 4 -->
+    <script async src="https://www.googletagmanager.com/gtag/js?id=${config.measurementId}"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', '${config.measurementId}');
+    </script>`;
+}
+
+/**
+ * Simple framework detection for tracking injection
+ */
+function detectFrameworkSimple(projectPath: string): string {
+  // Check for Next.js
+  if (fs.existsSync(path.join(projectPath, 'next.config.js')) ||
+      fs.existsSync(path.join(projectPath, 'next.config.ts')) ||
+      fs.existsSync(path.join(projectPath, 'next.config.mjs'))) {
+    return 'nextjs';
+  }
+
+  // Check for Vite
+  if (fs.existsSync(path.join(projectPath, 'vite.config.js')) ||
+      fs.existsSync(path.join(projectPath, 'vite.config.ts'))) {
+    return 'vite';
+  }
+
+  // Check for plain HTML
+  if (fs.existsSync(path.join(projectPath, 'index.html'))) {
+    return 'html';
+  }
+
+  // Check for React (CRA)
+  const pkgPath = path.join(projectPath, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg.dependencies?.react || pkg.devDependencies?.react) {
+        return 'react';
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Auto-detect framework and inject GA4
+ */
+export async function injectGA4(projectPath: string, config: GA4Config): Promise<InjectionResult> {
+  const framework = detectFrameworkSimple(projectPath);
+
+  switch (framework) {
+    case 'nextjs':
+      return injectGA4NextJs(projectPath, config);
+    case 'vite':
+    case 'react':
+      return injectGA4Vite(projectPath, config);
+    case 'html':
+      return injectGA4Html(projectPath, config);
+    default:
+      return {
+        success: false,
+        message: `Unsupported framework: ${framework}. Please manually add GA4.`,
+        code: generateGA4Script(config),
+      };
+  }
+}
+
+async function injectGA4NextJs(projectPath: string, config: GA4Config): Promise<InjectionResult> {
+  // Check for app directory (App Router) or pages directory (Pages Router)
+  const appLayoutPath = path.join(projectPath, 'app', 'layout.tsx');
+  const pagesAppPath = path.join(projectPath, 'pages', '_app.tsx');
+  const srcAppLayoutPath = path.join(projectPath, 'src', 'app', 'layout.tsx');
+  const srcPagesAppPath = path.join(projectPath, 'src', 'pages', '_app.tsx');
+
+  // Try App Router first
+  for (const layoutPath of [appLayoutPath, srcAppLayoutPath]) {
+    if (fs.existsSync(layoutPath)) {
+      const content = fs.readFileSync(layoutPath, 'utf-8');
+
+      // Check if GA4 already exists
+      if (content.includes('googletagmanager.com/gtag')) {
+        return { success: true, file: layoutPath, message: 'GA4 already installed' };
+      }
+
+      // Create GoogleAnalytics component
+      const componentsDir = path.join(path.dirname(layoutPath), '..', 'components');
+      if (!fs.existsSync(componentsDir)) {
+        fs.mkdirSync(componentsDir, { recursive: true });
+      }
+
+      const gaComponentPath = path.join(componentsDir, 'GoogleAnalytics.tsx');
+      fs.writeFileSync(gaComponentPath, generateGA4ReactComponent(config));
+
+      // Update layout to import and use component
+      const importStatement = `import { GoogleAnalytics } from '@/components/GoogleAnalytics';\n`;
+      const componentUsage = '<GoogleAnalytics />';
+
+      // Add import at top
+      let newContent = content;
+      if (!newContent.includes('GoogleAnalytics')) {
+        // Find first import or add at top
+        const importMatch = newContent.match(/^import .+$/m);
+        if (importMatch) {
+          newContent = newContent.replace(importMatch[0], importMatch[0] + '\n' + importStatement);
+        } else {
+          newContent = importStatement + newContent;
+        }
+
+        // Add component inside <head> or <body>
+        if (newContent.includes('<head>')) {
+          newContent = newContent.replace('<head>', `<head>\n        ${componentUsage}`);
+        } else if (newContent.includes('<body')) {
+          newContent = newContent.replace(/<body([^>]*)>/, `<body$1>\n        ${componentUsage}`);
+        }
+
+        fs.writeFileSync(layoutPath, newContent);
+      }
+
+      return {
+        success: true,
+        file: layoutPath,
+        message: `GA4 component created at ${gaComponentPath} and imported in layout`,
+      };
+    }
+  }
+
+  // Try Pages Router
+  for (const appPath of [pagesAppPath, srcPagesAppPath]) {
+    if (fs.existsSync(appPath)) {
+      return {
+        success: false,
+        file: appPath,
+        message: 'Pages Router detected. Please manually add GA4 to _app.tsx',
+        code: generateGA4ReactComponent(config),
+      };
+    }
+  }
+
+  return {
+    success: false,
+    message: 'Could not find Next.js layout or _app file',
+    code: generateGA4ReactComponent(config),
+  };
+}
+
+async function injectGA4Vite(projectPath: string, config: GA4Config): Promise<InjectionResult> {
+  // Look for index.html
+  const indexPaths = [
+    path.join(projectPath, 'index.html'),
+    path.join(projectPath, 'public', 'index.html'),
+    path.join(projectPath, 'src', 'index.html'),
+  ];
+
+  for (const indexPath of indexPaths) {
+    if (fs.existsSync(indexPath)) {
+      let content = fs.readFileSync(indexPath, 'utf-8');
+
+      // Check if already installed
+      if (content.includes('googletagmanager.com/gtag')) {
+        return { success: true, file: indexPath, message: 'GA4 already installed' };
+      }
+
+      // Inject before </head>
+      const ga4Script = generateGA4ViteScript(config);
+      content = content.replace('</head>', `${ga4Script}\n  </head>`);
+
+      fs.writeFileSync(indexPath, content);
+      return {
+        success: true,
+        file: indexPath,
+        message: `GA4 injected into ${indexPath}`,
+      };
+    }
+  }
+
+  return {
+    success: false,
+    message: 'Could not find index.html',
+    code: generateGA4Script(config),
+  };
+}
+
+async function injectGA4Html(projectPath: string, config: GA4Config): Promise<InjectionResult> {
+  return injectGA4Vite(projectPath, config); // Same logic
+}
+
+/**
+ * Generate environment variable template for GA4
+ */
+export function generateGA4EnvTemplate(): string {
+  return `# Google Analytics 4
+# Get your Measurement ID from: https://analytics.google.com
+# Go to: Admin > Data Streams > Your Stream > Measurement ID
+VITE_GA4_MEASUREMENT_ID=G-XXXXXXXXXX
+# or for Next.js:
+NEXT_PUBLIC_GA4_MEASUREMENT_ID=G-XXXXXXXXXX`;
+}

package/src/tracking/index.ts

@@ -0,0 +1,45 @@
+// Tracking & Monitoring Module
+// Google Analytics, Search Console integration, and automated reporting
+
+// Google Analytics 4
+export {
+  generateGA4Script,
+  generateGA4ReactComponent,
+  generateGA4ViteScript,
+  generateGA4EnvTemplate,
+  injectGA4,
+  type GA4Config,
+  type InjectionResult,
+} from './google-analytics.js';
+
+// Google Search Console
+export {
+  generateGSCVerificationTag,
+  injectGSCVerification,
+  buildGSCApiRequest,
+  parseGSCResponse,
+  identifyQuickWins,
+  comparePeriods,
+  getGSCSetupInstructions,
+  type GSCConfig,
+  type GSCCredentials,
+  type GSCQueryResult,
+  type GSCPerformanceData,
+  type QuickWin,
+} from './search-console.js';
+
+// GitHub Action
+export {
+  generateWorkflow,
+  generateSecretsDoc,
+  generateGitHubActionSetup,
+  writeGitHubActionFiles,
+  type WorkflowConfig,
+} from './github-action.js';
+
+// Report Generator
+export {
+  generateMarkdownReport,
+  generateJsonReport,
+  type ReportData,
+} from './report-generator.js';

package/src/tracking/report-generator.ts

@@ -0,0 +1,386 @@
+// SEO Report Generator
+// Creates formatted reports for GitHub Issues and dashboards
+
+import type { AuditReport, AuditIssue } from '../audit/index.js';
+import type { GSCPerformanceData, QuickWin } from './search-console.js';
+
+export interface ReportData {
+  siteUrl: string;
+  generatedAt: string;
+  audit?: AuditReport;
+  tracking?: {
+    current: GSCPerformanceData;
+    previous?: GSCPerformanceData;
+    quickWins: QuickWin[];
+  };
+  comparison?: {
+    improved: any[];
+    declined: any[];
+    newKeywords: any[];
+    lostKeywords: any[];
+    summary: {
+      clicksChange: number;
+      impressionsChange: number;
+      avgPositionChange: number;
+    };
+  };
+}
+
+/**
+ * Generate comprehensive markdown report
+ */
+export function generateMarkdownReport(data: ReportData): string {
+  const lines: string[] = [];
+  const date = new Date(data.generatedAt).toLocaleDateString('en-US', {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  });
+
+  lines.push(`# 📊 SEO Report: ${data.siteUrl}`);
+  lines.push(`> Generated: ${date}`);
+  lines.push('');
+
+  // Executive Summary
+  lines.push('## 📋 Executive Summary');
+  lines.push('');
+  lines.push(generateExecutiveSummary(data));
+  lines.push('');
+
+  // Health Score (if audit data)
+  if (data.audit) {
+    lines.push('## 🏥 Site Health');
+    lines.push('');
+    lines.push(generateHealthSection(data.audit));
+    lines.push('');
+  }
+
+  // Traffic & Rankings (if tracking data)
+  if (data.tracking) {
+    lines.push('## 📈 Traffic & Rankings');
+    lines.push('');
+    lines.push(generateTrackingSection(data.tracking, data.comparison));
+    lines.push('');
+  }
+
+  // Quick Wins
+  if (data.tracking?.quickWins && data.tracking.quickWins.length > 0) {
+    lines.push('## 🎯 Quick Wins');
+    lines.push('');
+    lines.push(generateQuickWinsSection(data.tracking.quickWins));
+    lines.push('');
+  }
+
+  // Issues to Fix (if audit data)
+  if (data.audit && data.audit.issues.length > 0) {
+    lines.push('## 🔧 Issues to Fix');
+    lines.push('');
+    lines.push(generateIssuesSection(data.audit));
+    lines.push('');
+  }
+
+  // Action Items
+  lines.push('## ✅ Recommended Actions');
+  lines.push('');
+  lines.push(generateActionItems(data));
+  lines.push('');
+
+  // Footer
+  lines.push('---');
+  lines.push('');
+  lines.push('*Generated by [SEO Autopilot](https://github.com/seo-autopilot) 🤖*');
+
+  return lines.join('\n');
+}
+
+function generateExecutiveSummary(data: ReportData): string {
+  const lines: string[] = [];
+
+  if (data.audit) {
+    const score = data.audit.healthScore.overall;
+    const emoji = score >= 80 ? '🟢' : score >= 60 ? '🟡' : '🔴';
+    const totalIssues = data.audit.summary.errors + data.audit.summary.warnings + data.audit.summary.notices;
+    const totalChecks = totalIssues + data.audit.summary.passed;
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| ${emoji} Health Score | **${score}/100** |`);
+    lines.push(`| Issues Found | ${data.audit.issues.length} |`);
+    lines.push(`| Checks Passed | ${data.audit.summary.passed}/${totalChecks} |`);
+  }
+
+  if (data.tracking) {
+    if (!data.audit) {
+      lines.push(`| Metric | Value |`);
+      lines.push(`|--------|-------|`);
+    }
+    lines.push(`| Total Clicks | ${data.tracking.current.totalClicks.toLocaleString()} |`);
+    lines.push(`| Total Impressions | ${data.tracking.current.totalImpressions.toLocaleString()} |`);
+    lines.push(`| Avg Position | ${data.tracking.current.avgPosition.toFixed(1)} |`);
+    lines.push(`| Avg CTR | ${(data.tracking.current.avgCtr * 100).toFixed(2)}% |`);
+  }
+
+  if (data.comparison) {
+    lines.push('');
+    lines.push('### Week-over-Week Changes');
+    lines.push('');
+
+    const clicksChange = data.comparison.summary.clicksChange;
+    const impressionsChange = data.comparison.summary.impressionsChange;
+    const positionChange = data.comparison.summary.avgPositionChange;
+
+    const clicksEmoji = clicksChange > 0 ? '📈' : clicksChange < 0 ? '📉' : '➡️';
+    const impressionsEmoji = impressionsChange > 0 ? '📈' : impressionsChange < 0 ? '📉' : '➡️';
+    const positionEmoji = positionChange < 0 ? '📈' : positionChange > 0 ? '📉' : '➡️'; // Lower is better
+
+    lines.push(`- ${clicksEmoji} Clicks: ${clicksChange >= 0 ? '+' : ''}${clicksChange.toLocaleString()}`);
+    lines.push(`- ${impressionsEmoji} Impressions: ${impressionsChange >= 0 ? '+' : ''}${impressionsChange.toLocaleString()}`);
+    lines.push(`- ${positionEmoji} Avg Position: ${positionChange >= 0 ? '+' : ''}${positionChange.toFixed(1)}`);
+  }
+
+  return lines.join('\n');
+}
+
+function generateHealthSection(audit: AuditReport): string {
+  const lines: string[] = [];
+
+  // Visual score bar
+  const score = audit.healthScore.overall;
+  const filled = Math.round(score / 10);
+  const empty = 10 - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+
+  lines.push(`### Score: ${score}/100`);
+  lines.push('');
+  lines.push(`\`${bar}\``);
+  lines.push('');
+
+  // Category breakdown
+  const categories = new Map<string, { passed: number; total: number }>();
+
+  for (const issue of audit.issues) {
+    const cat = issue.category;
+    if (!categories.has(cat)) {
+      categories.set(cat, { passed: 0, total: 0 });
+    }
+    categories.get(cat)!.total++;
+  }
+
+  if (categories.size > 0) {
+    lines.push('| Category | Issues |');
+    lines.push('|----------|--------|');
+
+    for (const [category, counts] of categories) {
+      const icon = counts.total === 0 ? '✅' : counts.total <= 2 ? '⚠️' : '❌';
+      lines.push(`| ${icon} ${category} | ${counts.total} |`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function generateTrackingSection(
+  tracking: ReportData['tracking'],
+  comparison?: ReportData['comparison']
+): string {
+  if (!tracking) return '';
+
+  const lines: string[] = [];
+
+  // Top performing queries
+  lines.push('### Top Performing Queries');
+  lines.push('');
+  lines.push('| Query | Clicks | Impressions | Position | CTR |');
+  lines.push('|-------|--------|-------------|----------|-----|');
+
+  const topQueries = tracking.current.queries
+    .sort((a, b) => b.clicks - a.clicks)
+    .slice(0, 10);
+
+  for (const q of topQueries) {
+    lines.push(`| ${truncate(q.query, 40)} | ${q.clicks} | ${q.impressions} | ${q.position.toFixed(1)} | ${(q.ctr * 100).toFixed(1)}% |`);
+  }
+
+  // Comparison data
+  if (comparison) {
+    if (comparison.improved.length > 0) {
+      lines.push('');
+      lines.push('### 📈 Improved Rankings');
+      lines.push('');
+      for (const q of comparison.improved.slice(0, 5)) {
+        lines.push(`- **${q.query}**: Moved up to position ${q.position.toFixed(1)}`);
+      }
+    }
+
+    if (comparison.declined.length > 0) {
+      lines.push('');
+      lines.push('### 📉 Declined Rankings');
+      lines.push('');
+      for (const q of comparison.declined.slice(0, 5)) {
+        lines.push(`- **${q.query}**: Dropped to position ${q.position.toFixed(1)}`);
+      }
+    }
+
+    if (comparison.newKeywords.length > 0) {
+      lines.push('');
+      lines.push('### 🆕 New Keywords');
+      lines.push('');
+      for (const q of comparison.newKeywords.slice(0, 5)) {
+        lines.push(`- **${q.query}**: Position ${q.position.toFixed(1)} (${q.impressions} impressions)`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function generateQuickWinsSection(quickWins: QuickWin[]): string {
+  const lines: string[] = [];
+
+  lines.push('These are high-impact opportunities requiring minimal effort:');
+  lines.push('');
+
+  for (const win of quickWins.slice(0, 10)) {
+    const typeIcon = win.opportunity === 'page-1-close' ? '🎯' :
+                     win.opportunity === 'low-ctr' ? '📝' : '⬆️';
+
+    lines.push(`### ${typeIcon} ${truncate(win.query, 50)}`);
+    lines.push('');
+    lines.push(`- **Current Position**: ${win.currentPosition.toFixed(1)}`);
+    lines.push(`- **Impressions**: ${win.impressions.toLocaleString()}/month`);
+    lines.push(`- **Current CTR**: ${(win.ctr * 100).toFixed(1)}%`);
+    lines.push(`- **Potential Gain**: +${win.potentialGain} clicks/month`);
+    lines.push(`- **Action**: ${win.suggestedAction}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function generateIssuesSection(audit: AuditReport): string {
+  const lines: string[] = [];
+
+  // Group by severity
+  const errors = audit.issues.filter((i: AuditIssue) => i.severity === 'error');
+  const warnings = audit.issues.filter((i: AuditIssue) => i.severity === 'warning');
+  const notices = audit.issues.filter((i: AuditIssue) => i.severity === 'notice');
+
+  if (errors.length > 0) {
+    lines.push('### ❌ Errors (Fix Immediately)');
+    lines.push('');
+    for (const issue of errors.slice(0, 10)) {
+      lines.push(`- **${issue.code}**: ${issue.title}`);
+      if (issue.affectedUrls && issue.affectedUrls.length > 0) {
+        lines.push(`  - URL: \`${issue.affectedUrls[0]}\``);
+      }
+    }
+    lines.push('');
+  }
+
+  if (warnings.length > 0) {
+    lines.push('### ⚠️ Warnings (Should Fix)');
+    lines.push('');
+    for (const issue of warnings.slice(0, 10)) {
+      lines.push(`- **${issue.code}**: ${issue.title}`);
+    }
+    lines.push('');
+  }
+
+  if (notices.length > 0) {
+    lines.push('<details>');
+    lines.push('<summary>📝 Notices (Consider Fixing) - ' + notices.length + ' items</summary>');
+    lines.push('');
+    for (const issue of notices.slice(0, 20)) {
+      lines.push(`- ${issue.code}: ${issue.title}`);
+    }
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function generateActionItems(data: ReportData): string {
+  const lines: string[] = [];
+  const actions: string[] = [];
+
+  // From audit issues
+  if (data.audit) {
+    const errors = data.audit.issues.filter((i: AuditIssue) => i.severity === 'error');
+    if (errors.length > 0) {
+      actions.push(`Fix ${errors.length} critical SEO errors`);
+    }
+
+    const missingMeta = data.audit.issues.filter((i: AuditIssue) =>
+      i.code.includes('TITLE') || i.code.includes('META')
+    );
+    if (missingMeta.length > 0) {
+      actions.push(`Add missing meta tags on ${missingMeta.length} pages`);
+    }
+  }
+
+  // From quick wins
+  if (data.tracking?.quickWins) {
+    const pageOneClose = data.tracking.quickWins.filter(w => w.opportunity === 'page-1-close');
+    if (pageOneClose.length > 0) {
+      actions.push(`Optimize ${pageOneClose.length} keywords that are almost on page 1`);
+    }
+
+    const lowCtr = data.tracking.quickWins.filter(w => w.opportunity === 'low-ctr');
+    if (lowCtr.length > 0) {
+      actions.push(`Improve titles/descriptions for ${lowCtr.length} low-CTR pages`);
+    }
+  }
+
+  // From comparison
+  if (data.comparison?.declined && data.comparison.declined.length > 0) {
+    actions.push(`Investigate ${data.comparison.declined.length} keywords with declining rankings`);
+  }
+
+  if (actions.length === 0) {
+    actions.push('Continue monitoring - no urgent actions needed');
+  }
+
+  lines.push('Priority order:');
+  lines.push('');
+  for (let i = 0; i < actions.length; i++) {
+    lines.push(`${i + 1}. [ ] ${actions[i]}`);
+  }
+
+  return lines.join('\n');
+}
+
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+/**
+ * Generate JSON report for API/dashboard
+ */
+export function generateJsonReport(data: ReportData): object {
+  return {
+    meta: {
+      siteUrl: data.siteUrl,
+      generatedAt: data.generatedAt,
+      version: '1.0',
+    },
+    health: data.audit ? {
+      score: data.audit.healthScore.overall,
+      issueCount: data.audit.issues.length,
+      passed: data.audit.summary.passed,
+      errors: data.audit.summary.errors,
+      warnings: data.audit.summary.warnings,
+      notices: data.audit.summary.notices,
+    } : null,
+    traffic: data.tracking ? {
+      clicks: data.tracking.current.totalClicks,
+      impressions: data.tracking.current.totalImpressions,
+      avgPosition: data.tracking.current.avgPosition,
+      avgCtr: data.tracking.current.avgCtr,
+    } : null,
+    quickWins: data.tracking?.quickWins || [],
+    issues: data.audit?.issues || [],
+    comparison: data.comparison || null,
+  };
+}