@rankcli/agent-runtime 0.0.1

package/src/tools/h1-fixer.ts

@@ -0,0 +1,249 @@
+import { readdirSync, readFileSync, statSync, existsSync } from 'fs';
+import { join, extname } from 'path';
+import type { ToolResult } from '../types.js';
+import type { GeneratedFix } from '../fixer.js';
+
+interface H1ScanResult {
+  hasH1: boolean;
+  h1Location?: {
+    file: string;
+    line: number;
+    content: string;
+  };
+  candidates: HeadlineCandidate[];
+}
+
+interface HeadlineCandidate {
+  file: string;
+  line: number;
+  tag: string;
+  className: string;
+  content: string;
+  score: number; // Higher = more likely to be the main headline
+}
+
+// Tailwind text size classes ranked by size
+const TEXT_SIZE_SCORES: Record<string, number> = {
+  'text-9xl': 100,
+  'text-8xl': 90,
+  'text-7xl': 80,
+  'text-6xl': 70,
+  'text-5xl': 60,
+  'text-4xl': 50,
+  'text-3xl': 40,
+  'text-2xl': 30,
+  'text-xl': 20,
+};
+
+// Component names that likely contain the main headline
+const PRIORITY_COMPONENTS = ['hero', 'landing', 'home', 'index', 'main'];
+
+export async function scanForH1(params: { cwd: string }): Promise<ToolResult> {
+  const { cwd } = params;
+  const result: H1ScanResult = {
+    hasH1: false,
+    candidates: [],
+  };
+
+  const srcDir = join(cwd, 'src');
+  if (!existsSync(srcDir)) {
+    return { success: true, data: result };
+  }
+
+  const files = findReactFiles(srcDir);
+
+  // Store all H1 locations to find the best one
+  const h1Locations: Array<{ file: string; line: number; content: string; priority: number }> = [];
+
+  for (const file of files) {
+    const content = readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+    const relativePath = file.replace(cwd + '/', '');
+
+    // Check for existing H1
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Look for <h1 or <H1 in JSX
+      if (/<h1[\s>]/i.test(line)) {
+        // Calculate priority based on file location
+        let priority = 0;
+        const lowerPath = relativePath.toLowerCase();
+        if (lowerPath.includes('hero')) priority += 100;
+        if (lowerPath.includes('landing')) priority += 80;
+        if (lowerPath.includes('home')) priority += 70;
+        if (lowerPath.includes('index')) priority += 60;
+        if (lowerPath.includes('main')) priority += 50;
+        if (lowerPath.includes('components/landing')) priority += 40;
+
+        h1Locations.push({
+          file: relativePath,
+          line: i + 1,
+          content: line.trim(),
+          priority,
+        });
+      }
+
+      // Look for headline candidates (large text that's not an H1)
+      const candidate = findHeadlineCandidate(line, i + 1, relativePath);
+      if (candidate) {
+        result.candidates.push(candidate);
+      }
+    }
+  }
+
+  // If we found H1s, use the highest priority one
+  if (h1Locations.length > 0) {
+    h1Locations.sort((a, b) => b.priority - a.priority);
+    const best = h1Locations[0];
+    result.hasH1 = true;
+    result.h1Location = {
+      file: best.file,
+      line: best.line,
+      content: best.content,
+    };
+  }
+
+  // Sort candidates by score (highest first)
+  result.candidates.sort((a, b) => b.score - a.score);
+
+  // Boost score for components in priority list
+  for (const candidate of result.candidates) {
+    const fileName = candidate.file.toLowerCase();
+    for (const priority of PRIORITY_COMPONENTS) {
+      if (fileName.includes(priority)) {
+        candidate.score += 25;
+      }
+    }
+  }
+
+  // Re-sort after boosting
+  result.candidates.sort((a, b) => b.score - a.score);
+
+  return { success: true, data: result };
+}
+
+function findReactFiles(dir: string): string[] {
+  const files: string[] = [];
+
+  function scan(currentDir: string) {
+    const entries = readdirSync(currentDir);
+    for (const entry of entries) {
+      if (entry.startsWith('.') || entry === 'node_modules') continue;
+
+      const fullPath = join(currentDir, entry);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        // Skip ui components directory - these are usually shadcn/ui
+        if (entry !== 'ui' || !currentDir.includes('components')) {
+          scan(fullPath);
+        }
+      } else if (['.tsx', '.jsx'].includes(extname(entry))) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  scan(dir);
+  return files;
+}
+
+function findHeadlineCandidate(line: string, lineNum: number, file: string): HeadlineCandidate | null {
+  // Match patterns like <div className="text-5xl or <p className="... text-4xl
+  const tagMatch = line.match(/<(div|p|span|section)\s+[^>]*className=["']([^"']*text-[3-9]xl[^"']*)["']/i);
+
+  if (!tagMatch) return null;
+
+  const [, tag, className] = tagMatch;
+
+  // Calculate score based on text size
+  let score = 0;
+  for (const [sizeClass, points] of Object.entries(TEXT_SIZE_SCORES)) {
+    if (className.includes(sizeClass)) {
+      score = points;
+      break;
+    }
+  }
+
+  // Boost for bold
+  if (className.includes('font-bold') || className.includes('font-extrabold')) {
+    score += 10;
+  }
+
+  // Extract text content if on same line
+  const textMatch = line.match(/>([^<]+)</);
+  const content = textMatch ? textMatch[1].trim() : '';
+
+  return {
+    file,
+    line: lineNum,
+    tag,
+    className,
+    content,
+    score,
+  };
+}
+
+export async function generateH1Fix(params: { cwd: string }): Promise<GeneratedFix | null> {
+  const scanResult = await scanForH1(params);
+
+  if (!scanResult.success || !scanResult.data) {
+    return null;
+  }
+
+  const data = scanResult.data as H1ScanResult;
+
+  // If H1 already exists, no fix needed
+  if (data.hasH1) {
+    return {
+      issue: {
+        code: 'MISSING_H1',
+        message: 'No H1 heading found',
+        severity: 'critical',
+      },
+      file: data.h1Location!.file,
+      before: null,
+      after: data.h1Location!.content,
+      explanation: `H1 already exists in component at line ${data.h1Location!.line}. The audit may not see it because it's rendered by JavaScript. Google's crawler does execute JS.`,
+      skipped: true,
+      skipReason: `H1 found in ${data.h1Location!.file}:${data.h1Location!.line} (JS-rendered)`,
+    };
+  }
+
+  // No H1 and no candidates
+  if (data.candidates.length === 0) {
+    return {
+      issue: {
+        code: 'MISSING_H1',
+        message: 'No H1 heading found',
+        severity: 'critical',
+      },
+      file: 'Unknown',
+      before: null,
+      after: '<h1>Your Main Headline</h1>',
+      explanation: 'No suitable headline element found to convert. Add an H1 manually in your main page component.',
+      skipped: true,
+      skipReason: 'No headline-like elements found to convert',
+    };
+  }
+
+  // Get the best candidate
+  const best = data.candidates[0];
+
+  // Generate the fix
+  const before = `<${best.tag}`;
+  const after = `<h1`;
+
+  return {
+    issue: {
+      code: 'MISSING_H1',
+      message: 'No H1 heading found',
+      severity: 'critical',
+    },
+    file: best.file,
+    before,
+    after,
+    explanation: `Convert the main headline from <${best.tag}> to <h1>. Found at line ${best.line} with classes: ${best.className}`,
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,67 @@
+import {
+  crawlUrl,
+  extractMeta,
+  analyzeHeadings,
+  extractImages,
+  extractLinks,
+  extractSchema,
+  checkRobots,
+  checkSitemap,
+} from './crawl.js';
+
+import {
+  readFile,
+  writeFile,
+  listFiles,
+  detectFramework,
+  findHtmlEntry,
+  findPageFiles,
+} from './files.js';
+
+import { analyzeUrl } from './analyzer.js';
+import { scanForH1, generateH1Fix } from './h1-fixer.js';
+
+import type { ToolFunction } from '../types.js';
+
+export const tools: Record<string, ToolFunction> = {
+  // Crawling tools
+  crawl_url: (params) => crawlUrl(params as { url: string }),
+  extract_meta: (params) => extractMeta(params as { html: string; url: string }),
+  analyze_headings: (params) => analyzeHeadings(params as { html: string }),
+  extract_images: (params) => extractImages(params as { html: string }),
+  extract_links: (params) => extractLinks(params as { html: string; baseUrl: string }),
+  extract_schema: (params) => extractSchema(params as { html: string }),
+  check_robots: (params) => checkRobots(params as { url: string }),
+  check_sitemap: (params) => checkSitemap(params as { url: string }),
+
+  // File tools
+  read_file: (params) => readFile(params as { path: string; cwd?: string }),
+  write_file: (params) => writeFile(params as { path: string; content: string; cwd?: string }),
+  list_files: (params) => listFiles(params as { path: string; cwd?: string; pattern?: string; recursive?: boolean }),
+  detect_framework: (params) => detectFramework(params as { cwd?: string }),
+  find_html_entry: (params) => findHtmlEntry(params as { cwd?: string }),
+  find_page_files: (params) => findPageFiles(params as { cwd?: string; framework?: string }),
+
+  // High-level analysis
+  analyze_url: (params) => analyzeUrl(params as { url: string }),
+};
+
+export {
+  crawlUrl,
+  extractMeta,
+  analyzeHeadings,
+  extractImages,
+  extractLinks,
+  extractSchema,
+  checkRobots,
+  checkSitemap,
+  readFile,
+  writeFile,
+  listFiles,
+  detectFramework,
+  findHtmlEntry,
+  findPageFiles,
+  analyzeUrl,
+  scanForH1,
+  generateH1Fix,
+};

package/src/tracking/github-action.ts

@@ -0,0 +1,326 @@
+// GitHub Action Workflow Generator
+// Creates scheduled SEO monitoring workflows
+
+export interface WorkflowConfig {
+  schedule: 'daily' | 'weekly' | 'monthly' | 'manual';
+  siteUrl: string;
+  features: {
+    audit: boolean;
+    tracking: boolean;
+    autoFix: boolean;
+    createIssues: boolean;
+    createPRs: boolean;
+  };
+  apiKey?: string; // SEO Autopilot API key for paid features
+}
+
+/**
+ * Generate GitHub Action workflow YAML
+ */
+export function generateWorkflow(config: WorkflowConfig): string {
+  const cronSchedule = getCronSchedule(config.schedule);
+
+  return `# SEO Autopilot - Automated SEO Monitoring
+# This workflow runs scheduled SEO audits and tracking
+
+name: SEO Monitoring
+
+on:
+  # Scheduled runs
+  schedule:
+    - cron: '${cronSchedule}'
+
+  # Manual trigger
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: 'Run mode'
+        required: true
+        default: 'full'
+        type: choice
+        options:
+          - full
+          - audit-only
+          - track-only
+
+  # Run on main branch pushes (optional)
+  # push:
+  #   branches: [main]
+
+env:
+  SITE_URL: '${config.siteUrl}'
+
+jobs:
+  seo-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install SEO Autopilot
+        run: npm install -g @seo-autopilot/cli
+
+      ${config.features.tracking ? `
+      - name: Pull GSC Data
+        if: \${{ inputs.mode != 'audit-only' }}
+        env:
+          GSC_SERVICE_ACCOUNT_EMAIL: \${{ secrets.GSC_SERVICE_ACCOUNT_EMAIL }}
+          GSC_PRIVATE_KEY: \${{ secrets.GSC_PRIVATE_KEY }}
+        run: |
+          seo track --site "$SITE_URL" --output tracking-report.json
+        continue-on-error: true
+      ` : ''}
+
+      ${config.features.audit ? `
+      - name: Run SEO Audit
+        if: \${{ inputs.mode != 'track-only' }}
+        run: |
+          seo audit --url "$SITE_URL" --output json > audit-report.json
+      ` : ''}
+
+      - name: Generate Report
+        id: report
+        run: |
+          seo report --combine \\
+            ${config.features.tracking ? '--tracking tracking-report.json \\' : ''}
+            ${config.features.audit ? '--audit audit-report.json \\' : ''}
+            --format markdown > seo-report.md
+
+          # Set output for issue creation
+          echo "report<<EOF" >> $GITHUB_OUTPUT
+          cat seo-report.md >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      ${config.features.createIssues ? `
+      - name: Create/Update Issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = 'SEO Report - ' + new Date().toISOString().split('T')[0];
+            const body = \`\${{ steps.report.outputs.report }}\`;
+
+            // Find existing issue
+            const issues = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: 'seo-report',
+              state: 'open'
+            });
+
+            if (issues.data.length > 0) {
+              // Update existing issue
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issues.data[0].number,
+                body: body
+              });
+              console.log('Updated issue #' + issues.data[0].number);
+            } else {
+              // Create new issue
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: title,
+                body: body,
+                labels: ['seo-report', 'automated']
+              });
+              console.log('Created new SEO report issue');
+            }
+      ` : ''}
+
+      ${config.features.autoFix && config.features.createPRs ? `
+      - name: Auto-fix Issues
+        id: autofix
+        run: |
+          # Run auto-fixer for safe, non-breaking changes
+          seo fix --auto --safe-only --output fixes.json
+
+          # Check if any fixes were made
+          if [ -s fixes.json ]; then
+            echo "fixes_made=true" >> $GITHUB_OUTPUT
+          else
+            echo "fixes_made=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create PR with Fixes
+        if: steps.autofix.outputs.fixes_made == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: \${{ secrets.GITHUB_TOKEN }}
+          commit-message: 'fix(seo): automated SEO improvements'
+          title: '🔧 SEO Auto-Fix: Automated Improvements'
+          body: |
+            ## Automated SEO Fixes
+
+            This PR was automatically generated by SEO Autopilot.
+
+            ### Changes Made
+            \`\`\`
+            $(cat fixes.json | jq -r '.fixes[] | "- " + .description')
+            \`\`\`
+
+            ### Review Checklist
+            - [ ] Changes look correct
+            - [ ] No unintended modifications
+            - [ ] Tests pass
+
+            ---
+            🤖 Generated by [SEO Autopilot](https://github.com/seo-autopilot)
+          branch: seo-autofix-\${{ github.run_number }}
+          labels: seo, automated
+      ` : ''}
+
+      - name: Save Report Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: seo-report-\${{ github.run_number }}
+          path: |
+            seo-report.md
+            ${config.features.audit ? 'audit-report.json' : ''}
+            ${config.features.tracking ? 'tracking-report.json' : ''}
+          retention-days: 90
+
+      ${config.apiKey ? `
+      - name: Send to SEO Autopilot Dashboard
+        env:
+          SEO_AUTOPILOT_API_KEY: \${{ secrets.SEO_AUTOPILOT_API_KEY }}
+        run: |
+          seo sync --api-key "$SEO_AUTOPILOT_API_KEY" \\
+            ${config.features.audit ? '--audit audit-report.json \\' : ''}
+            ${config.features.tracking ? '--tracking tracking-report.json' : ''}
+      ` : ''}
+`;
+}
+
+function getCronSchedule(schedule: WorkflowConfig['schedule']): string {
+  switch (schedule) {
+    case 'daily':
+      return '0 9 * * *'; // 9 AM UTC daily
+    case 'weekly':
+      return '0 9 * * 1'; // 9 AM UTC every Monday
+    case 'monthly':
+      return '0 9 1 * *'; // 9 AM UTC first of month
+    case 'manual':
+      return '0 0 31 2 *'; // Never (Feb 31 doesn't exist)
+    default:
+      return '0 9 * * 1';
+  }
+}
+
+/**
+ * Generate the secrets documentation
+ */
+export function generateSecretsDoc(config: WorkflowConfig): string {
+  let secrets = `# Required GitHub Secrets
+
+Go to your repository Settings > Secrets and variables > Actions
+
+`;
+
+  if (config.features.tracking) {
+    secrets += `
+## Google Search Console (Required for tracking)
+
+1. \`GSC_SERVICE_ACCOUNT_EMAIL\`
+   - Your Google Cloud service account email
+   - Example: seo-bot@my-project.iam.gserviceaccount.com
+
+2. \`GSC_PRIVATE_KEY\`
+   - The private key from your service account JSON
+   - Include the full key with -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----
+
+### Setup Instructions:
+1. Go to https://console.cloud.google.com
+2. Create a project and enable "Search Console API"
+3. Create a service account and download JSON key
+4. In Search Console, add the service account email as a user
+5. Copy email and private_key to GitHub Secrets
+
+`;
+  }
+
+  if (config.apiKey) {
+    secrets += `
+## SEO Autopilot (Required for dashboard sync)
+
+1. \`SEO_AUTOPILOT_API_KEY\`
+   - Get your API key from https://seo-autopilot.dev/dashboard
+   - This enables cloud dashboard, historical tracking, and alerts
+
+`;
+  }
+
+  return secrets;
+}
+
+/**
+ * Generate complete setup package
+ */
+export function generateGitHubActionSetup(config: WorkflowConfig): {
+  workflowYaml: string;
+  secretsDoc: string;
+  readmeBadge: string;
+} {
+  return {
+    workflowYaml: generateWorkflow(config),
+    secretsDoc: generateSecretsDoc(config),
+    readmeBadge: `[![SEO Status](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/seo.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/seo.yml)`,
+  };
+}
+
+/**
+ * Write GitHub Action files to project
+ */
+export function writeGitHubActionFiles(
+  projectPath: string,
+  config: WorkflowConfig
+): { files: string[]; instructions: string } {
+  const fs = require('fs');
+  const path = require('path');
+
+  const files: string[] = [];
+
+  // Create .github/workflows directory
+  const workflowDir = path.join(projectPath, '.github', 'workflows');
+  if (!fs.existsSync(workflowDir)) {
+    fs.mkdirSync(workflowDir, { recursive: true });
+  }
+
+  // Write workflow file
+  const workflowPath = path.join(workflowDir, 'seo.yml');
+  fs.writeFileSync(workflowPath, generateWorkflow(config));
+  files.push(workflowPath);
+
+  // Write secrets documentation
+  const docsDir = path.join(projectPath, '.github');
+  const secretsDocPath = path.join(docsDir, 'SEO_SETUP.md');
+  fs.writeFileSync(secretsDocPath, generateSecretsDoc(config));
+  files.push(secretsDocPath);
+
+  const instructions = `
+GitHub Action created! Next steps:
+
+1. Add required secrets to your repository:
+   Settings > Secrets and variables > Actions
+   See .github/SEO_SETUP.md for details
+
+2. The workflow will run ${config.schedule}
+   Or trigger manually: Actions > SEO Monitoring > Run workflow
+
+3. Add status badge to your README:
+   ${generateGitHubActionSetup(config).readmeBadge.replace('YOUR_ORG/YOUR_REPO', '<your-org>/<your-repo>')}
+`;
+
+  return { files, instructions };
+}