@rankcli/agent-runtime 0.0.15 → 0.0.16

package/src/tracking/google-analytics.ts

@@ -1,265 +0,0 @@
-// 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

@@ -1,45 +0,0 @@
-// 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

@@ -1,386 +0,0 @@
-// 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,
-  };
-}