@rankcli/agent-runtime 0.0.1

package/src/frameworks/suggestion-engine.ts

@@ -0,0 +1,320 @@
+/**
+ * Framework-Specific SEO Suggestion Engine
+ *
+ * Loads recipe files and provides framework-specific SEO suggestions.
+ * Works with both CLI and Web UI.
+ */
+
+import { parse as parseYaml } from 'yaml';
+import type { Framework, FrameworkInfo } from './detector.js';
+import type { AuditIssue, IssueCategory, IssueSeverity } from '../audit/types.js';
+
+export interface FrameworkCheck {
+  code: string;
+  severity: IssueSeverity;
+  title: string;
+  description: string;
+  howToFix: string;
+  impact?: string;
+  detection?: {
+    html_patterns?: string[];
+    missing_content?: boolean;
+    title_in_js?: boolean;
+    title_not_in_html?: boolean;
+  };
+  app_router_only?: boolean;
+  pages_router_only?: boolean;
+}
+
+export interface FrameworkRecipe {
+  framework: Framework;
+  display_name: string;
+  category: string;
+  base_framework?: Framework;
+  ssr_default: boolean;
+  seo_challenges?: string[];
+  seo_strengths?: string[];
+  checks: FrameworkCheck[];
+  performance_tips?: string[];
+  migration_paths?: Record<string, {
+    effort: string;
+    benefits: string[];
+    guide?: string;
+  }>;
+  recommended_plugins?: Record<string, string[]>;
+  recommended_gems?: Record<string, string[]>;
+  integrations?: string[];
+}
+
+// Embedded recipes (loaded at build time or dynamically)
+const RECIPES: Record<Framework, FrameworkRecipe | null> = {
+  react: null,
+  nextjs: null,
+  vue: null,
+  nuxt: null,
+  angular: null,
+  svelte: null,
+  sveltekit: null,
+  astro: null,
+  remix: null,
+  gatsby: null,
+  rails: null,
+  laravel: null,
+  django: null,
+  wordpress: null,
+  unknown: null,
+};
+
+// Recipe content will be bundled inline for distribution
+// This allows the suggestion engine to work without file system access
+const RECIPE_CONTENT: Record<string, string> = {};
+
+/**
+ * Load a recipe from embedded content or file system
+ */
+export async function loadRecipe(framework: Framework): Promise<FrameworkRecipe | null> {
+  if (framework === 'unknown') return null;
+
+  // Check cache
+  if (RECIPES[framework]) {
+    return RECIPES[framework];
+  }
+
+  // Check embedded content
+  if (RECIPE_CONTENT[framework]) {
+    try {
+      const recipe = parseYaml(RECIPE_CONTENT[framework]) as FrameworkRecipe;
+      RECIPES[framework] = recipe;
+      return recipe;
+    } catch {
+      console.warn(`Failed to parse embedded recipe for ${framework}`);
+      return null;
+    }
+  }
+
+  // Try dynamic import for Node.js environment
+  try {
+    const fs = await import('fs');
+    const path = await import('path');
+    const url = await import('url');
+
+    const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+    const recipePath = path.join(__dirname, 'recipes', `${framework}.yaml`);
+
+    if (fs.existsSync(recipePath)) {
+      const content = fs.readFileSync(recipePath, 'utf-8');
+      const recipe = parseYaml(content) as FrameworkRecipe;
+      RECIPES[framework] = recipe;
+      return recipe;
+    }
+  } catch {
+    // File system not available (browser, edge function)
+  }
+
+  return null;
+}
+
+/**
+ * Get framework-specific issues based on HTML analysis
+ */
+export async function getFrameworkIssues(
+  frameworkInfo: FrameworkInfo,
+  html: string,
+  url: string
+): Promise<AuditIssue[]> {
+  const recipe = await loadRecipe(frameworkInfo.framework);
+  if (!recipe) return [];
+
+  const issues: AuditIssue[] = [];
+
+  for (const check of recipe.checks) {
+    const matched = evaluateCheck(check, html, frameworkInfo);
+    if (matched) {
+      issues.push({
+        code: check.code,
+        severity: check.severity,
+        category: 'on-page' as IssueCategory, // Framework issues are on-page
+        title: check.title,
+        description: check.description,
+        impact: check.impact || `Framework-specific issue for ${recipe.display_name}`,
+        howToFix: check.howToFix,
+        affectedUrls: [url],
+        details: {
+          framework: recipe.display_name,
+          frameworkCategory: recipe.category,
+        },
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Evaluate if a check matches the HTML content
+ */
+function evaluateCheck(
+  check: FrameworkCheck,
+  html: string,
+  frameworkInfo: FrameworkInfo
+): boolean {
+  // Skip router-specific checks
+  if (check.app_router_only && !html.includes('__next')) {
+    return false;
+  }
+  if (check.pages_router_only && html.includes('__next')) {
+    return false;
+  }
+
+  const detection = check.detection;
+  if (!detection) {
+    // No detection rules, check is informational only
+    return false;
+  }
+
+  // Check HTML patterns
+  if (detection.html_patterns) {
+    for (const pattern of detection.html_patterns) {
+      if (html.includes(pattern)) {
+        return true;
+      }
+    }
+  }
+
+  // Check for missing content (SPA detection)
+  if (detection.missing_content) {
+    const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+    if (bodyMatch) {
+      const bodyContent = bodyMatch[1]
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        .replace(/<[^>]+>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+
+      // Less than 100 chars of text content = likely empty SPA
+      if (bodyContent.length < 100) {
+        return true;
+      }
+    }
+  }
+
+  // Check title in JS but not in HTML
+  if (detection.title_in_js && detection.title_not_in_html) {
+    const hasHtmlTitle = /<title[^>]*>[^<]+<\/title>/i.test(html);
+    const hasJsTitle = /document\.title\s*=/.test(html) ||
+                       /useHead|Helmet|useSeoMeta/.test(html);
+    if (!hasHtmlTitle && hasJsTitle) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get framework-specific suggestions for fixing issues
+ */
+export async function getFrameworkSuggestions(
+  frameworkInfo: FrameworkInfo,
+  issueCode: string
+): Promise<string | null> {
+  const recipe = await loadRecipe(frameworkInfo.framework);
+  if (!recipe) return null;
+
+  const check = recipe.checks.find(c => c.code === issueCode);
+  if (check) {
+    return check.howToFix;
+  }
+
+  return null;
+}
+
+/**
+ * Get all available checks for a framework
+ */
+export async function getFrameworkChecks(
+  framework: Framework
+): Promise<FrameworkCheck[]> {
+  const recipe = await loadRecipe(framework);
+  if (!recipe) return [];
+  return recipe.checks;
+}
+
+/**
+ * Get performance tips for a framework
+ */
+export async function getPerformanceTips(
+  framework: Framework
+): Promise<string[]> {
+  const recipe = await loadRecipe(framework);
+  if (!recipe) return [];
+  return recipe.performance_tips || [];
+}
+
+/**
+ * Get SEO challenges for a framework
+ */
+export async function getSeoChallenges(
+  framework: Framework
+): Promise<string[]> {
+  const recipe = await loadRecipe(framework);
+  if (!recipe) return [];
+  return recipe.seo_challenges || [];
+}
+
+/**
+ * Get migration paths from current framework
+ */
+export async function getMigrationPaths(
+  framework: Framework
+): Promise<Record<string, { effort: string; benefits: string[]; guide?: string }>> {
+  const recipe = await loadRecipe(framework);
+  if (!recipe) return {};
+  return recipe.migration_paths || {};
+}
+
+/**
+ * Get total number of framework-specific checks
+ */
+export async function getTotalFrameworkChecks(): Promise<number> {
+  let total = 0;
+  for (const framework of Object.keys(RECIPES) as Framework[]) {
+    const recipe = await loadRecipe(framework);
+    if (recipe) {
+      total += recipe.checks.length;
+    }
+  }
+  return total;
+}
+
+/**
+ * Get framework summary for display
+ */
+export async function getFrameworkSummary(framework: Framework): Promise<{
+  name: string;
+  category: string;
+  ssrDefault: boolean;
+  checkCount: number;
+  strengths: string[];
+  challenges: string[];
+} | null> {
+  const recipe = await loadRecipe(framework);
+  if (!recipe) return null;
+
+  return {
+    name: recipe.display_name,
+    category: recipe.category,
+    ssrDefault: recipe.ssr_default,
+    checkCount: recipe.checks.length,
+    strengths: recipe.seo_strengths || [],
+    challenges: recipe.seo_challenges || [],
+  };
+}
+
+/**
+ * Embed recipe content for bundling (called at build time)
+ */
+export function embedRecipe(framework: Framework, content: string): void {
+  RECIPE_CONTENT[framework] = content;
+}

package/src/geo/geo-content.test.ts

@@ -0,0 +1,305 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateAICitableContent,
+  generateFAQSchema,
+  generateComparisonTable,
+  generateKeyFacts,
+  optimizeForAI,
+  AIContentConfig,
+  FAQItem,
+  ComparisonRow,
+  KeyFact,
+} from './geo-content.js';
+
+describe('geo-content', () => {
+  describe('generateKeyFacts', () => {
+    it('formats facts with bold markers', () => {
+      const facts: KeyFact[] = [
+        { label: 'Users', value: '10,000+' },
+        { label: 'Checks', value: '200+' },
+      ];
+
+      const content = generateKeyFacts(facts);
+
+      expect(content).toContain('**Users:** 10,000+');
+      expect(content).toContain('**Checks:** 200+');
+    });
+
+    it('generates bullet list format', () => {
+      const facts: KeyFact[] = [
+        { label: 'Speed', value: 'Fast' },
+        { label: 'Price', value: 'Free' },
+      ];
+
+      const content = generateKeyFacts(facts, { format: 'bullets' });
+
+      expect(content).toContain('- **Speed:** Fast');
+      expect(content).toContain('- **Price:** Free');
+    });
+
+    it('generates paragraph format', () => {
+      const facts: KeyFact[] = [
+        { label: 'Founded', value: '2024' },
+      ];
+
+      const content = generateKeyFacts(facts, { format: 'paragraph' });
+
+      expect(content).not.toContain('- ');
+      expect(content).toContain('**Founded:** 2024');
+    });
+  });
+
+  describe('generateFAQSchema', () => {
+    it('generates valid FAQ schema JSON-LD', () => {
+      const faqs: FAQItem[] = [
+        { question: 'What is SEO Autopilot?', answer: 'A CLI-first SEO tool.' },
+        { question: 'How much does it cost?', answer: 'Free tier available.' },
+      ];
+
+      const schema = generateFAQSchema(faqs);
+      const parsed = JSON.parse(schema);
+
+      expect(parsed['@context']).toBe('https://schema.org');
+      expect(parsed['@type']).toBe('FAQPage');
+      expect(parsed.mainEntity).toHaveLength(2);
+      expect(parsed.mainEntity[0]['@type']).toBe('Question');
+    });
+
+    it('escapes special characters in JSON', () => {
+      const faqs: FAQItem[] = [
+        { question: 'What about "quotes"?', answer: 'They work fine.' },
+      ];
+
+      const schema = generateFAQSchema(faqs);
+
+      // Should be valid JSON
+      expect(() => JSON.parse(schema)).not.toThrow();
+    });
+
+    it('generates markdown FAQ section', () => {
+      const faqs: FAQItem[] = [
+        { question: 'How do I install?', answer: 'Run npm install.' },
+      ];
+
+      const markdown = generateFAQSchema(faqs, { format: 'markdown' });
+
+      expect(markdown).toContain('## FAQ');
+      expect(markdown).toContain('### How do I install?');
+      expect(markdown).toContain('Run npm install.');
+    });
+  });
+
+  describe('generateComparisonTable', () => {
+    it('generates markdown table', () => {
+      const rows: ComparisonRow[] = [
+        { feature: 'CLI Tool', brand: 'Yes', competitor: 'No' },
+        { feature: 'Auto-fix PRs', brand: 'Yes', competitor: 'No' },
+      ];
+
+      const table = generateComparisonTable(rows, {
+        brandName: 'SEO Autopilot',
+        competitorName: 'Ahrefs',
+      });
+
+      expect(table).toContain('| Feature | SEO Autopilot | Ahrefs |');
+      expect(table).toContain('| CLI Tool | Yes | No |');
+    });
+
+    it('uses checkmarks when specified', () => {
+      const rows: ComparisonRow[] = [
+        { feature: 'Free Tier', brand: true, competitor: false },
+      ];
+
+      const table = generateComparisonTable(rows, {
+        brandName: 'Us',
+        competitorName: 'Them',
+        useCheckmarks: true,
+      });
+
+      expect(table).toMatch(/✓|✅/);
+      expect(table).toMatch(/✗|❌|-/);
+    });
+
+    it('handles multiple competitors', () => {
+      const rows: ComparisonRow[] = [
+        { feature: 'Price', brand: '$29', competitors: { 'Ahrefs': '$99', 'SEMrush': '$129' } },
+      ];
+
+      const table = generateComparisonTable(rows, {
+        brandName: 'SEO Autopilot',
+        competitorNames: ['Ahrefs', 'SEMrush'],
+      });
+
+      expect(table).toContain('Ahrefs');
+      expect(table).toContain('SEMrush');
+      expect(table).toContain('$99');
+      expect(table).toContain('$129');
+    });
+  });
+
+  describe('generateAICitableContent', () => {
+    it('generates structured content block', () => {
+      const config: AIContentConfig = {
+        productName: 'SEO Autopilot',
+        tagline: 'CLI-first SEO automation',
+        keyFacts: [
+          { label: 'Checks', value: '200+' },
+        ],
+      };
+
+      const content = generateAICitableContent(config);
+
+      expect(content).toContain('SEO Autopilot');
+      expect(content).toContain('CLI-first SEO automation');
+      expect(content).toContain('**Checks:** 200+');
+    });
+
+    it('includes FAQ section when provided', () => {
+      const config: AIContentConfig = {
+        productName: 'Test Product',
+        faqs: [
+          { question: 'What is it?', answer: 'A great product.' },
+        ],
+      };
+
+      const content = generateAICitableContent(config);
+
+      expect(content).toContain('What is it?');
+      expect(content).toContain('A great product.');
+    });
+
+    it('includes comparison table when provided', () => {
+      const config: AIContentConfig = {
+        productName: 'SEO Autopilot',
+        comparison: {
+          competitorName: 'Competitor',
+          rows: [
+            { feature: 'CLI', brand: 'Yes', competitor: 'No' },
+          ],
+        },
+      };
+
+      const content = generateAICitableContent(config);
+
+      expect(content).toContain('CLI');
+      expect(content).toContain('Yes');
+      expect(content).toContain('No');
+    });
+
+    it('generates all sections in correct order', () => {
+      const config: AIContentConfig = {
+        productName: 'SEO Autopilot',
+        tagline: 'The developer SEO tool',
+        description: 'Full description here.',
+        keyFacts: [{ label: 'Users', value: '5000+' }],
+        faqs: [{ question: 'Q?', answer: 'A.' }],
+      };
+
+      const content = generateAICitableContent(config);
+
+      const taglineIndex = content.indexOf('developer SEO tool');
+      const factsIndex = content.indexOf('Users');
+      const faqIndex = content.indexOf('Q?');
+
+      expect(taglineIndex).toBeLessThan(factsIndex);
+      expect(factsIndex).toBeLessThan(faqIndex);
+    });
+  });
+
+  describe('optimizeForAI', () => {
+    it('adds citable markers to key statements', () => {
+      const content = 'SEO Autopilot runs 200 checks on your website.';
+
+      const optimized = optimizeForAI(content, {
+        highlightNumbers: true,
+      });
+
+      expect(optimized).toContain('**200**');
+    });
+
+    it('converts lists to structured format', () => {
+      const content = `Features include:
+speed, accuracy, and simplicity.`;
+
+      const optimized = optimizeForAI(content, {
+        structureLists: true,
+      });
+
+      expect(optimized).toContain('- ');
+    });
+
+    it('adds emphasis to brand mentions', () => {
+      const content = 'Use SEO Autopilot for better rankings.';
+
+      const optimized = optimizeForAI(content, {
+        brandName: 'SEO Autopilot',
+        emphasizeBrand: true,
+      });
+
+      expect(optimized).toContain('**SEO Autopilot**');
+    });
+
+    it('preserves existing markdown', () => {
+      const content = 'This is **already bold** text.';
+
+      const optimized = optimizeForAI(content, {
+        highlightNumbers: true,
+      });
+
+      expect(optimized).toContain('**already bold**');
+    });
+
+    it('adds source attribution placeholder', () => {
+      const content = 'Some facts here.';
+
+      const optimized = optimizeForAI(content, {
+        addSourcePlaceholder: true,
+      });
+
+      expect(optimized).toContain('Source:');
+    });
+  });
+
+  describe('integration', () => {
+    it('generates complete AI-optimized landing content', () => {
+      const config: AIContentConfig = {
+        productName: 'SEO Autopilot',
+        tagline: 'The CLI-First SEO Tool for Developers',
+        description: 'SEO Autopilot runs 200+ automated SEO checks directly from your terminal, making it the only developer-native SEO tool on the market.',
+        keyFacts: [
+          { label: 'Automated Checks', value: '200+' },
+          { label: 'GitHub Stars', value: '5,000+' },
+          { label: 'Monthly Downloads', value: '50,000+' },
+        ],
+        faqs: [
+          {
+            question: 'What is SEO Autopilot?',
+            answer: 'SEO Autopilot is a CLI-first SEO automation tool designed specifically for developers. It runs 200+ checks and can auto-fix issues via pull requests.',
+          },
+          {
+            question: 'How much does SEO Autopilot cost?',
+            answer: 'SEO Autopilot offers a free tier with 50 checks. Paid plans start at $9/month for Solo developers and $29/month for Pro teams.',
+          },
+        ],
+        comparison: {
+          competitorName: 'Ahrefs',
+          rows: [
+            { feature: 'CLI Tool', brand: 'Yes', competitor: 'No' },
+            { feature: 'Auto-fix PRs', brand: 'Yes', competitor: 'No' },
+            { feature: 'Free Tier', brand: 'Yes', competitor: 'No' },
+            { feature: 'Starting Price', brand: '$9/mo', competitor: '$99/mo' },
+          ],
+        },
+      };
+
+      const content = generateAICitableContent(config);
+
+      // Should have all major sections
+      expect(content).toContain('SEO Autopilot');
+      expect(content).toContain('200+');
+      expect(content).toContain('What is SEO Autopilot?');
+      expect(content).toContain('CLI Tool');
+      expect(content).toContain('$9/mo');
+    });
+  });
+});