@rankcli/agent-runtime 0.0.1

package/src/geo/geo-tracker.ts

@@ -0,0 +1,411 @@
+/**
+ * GEO (Generative Engine Optimization) Tracker
+ *
+ * Tracks brand visibility in LLM responses to understand how AI models
+ * recommend or mention your brand for relevant queries.
+ */
+
+export type MentionType = 'brand' | 'domain' | 'alternative';
+export type LLMProvider = 'openai' | 'anthropic' | 'google' | 'perplexity';
+export type Sentiment = 'positive' | 'negative' | 'neutral';
+
+export interface BrandConfig {
+  brandName: string;
+  domains: string[];
+  alternativeNames?: string[];
+}
+
+export interface Mention {
+  type: MentionType;
+  text: string;
+  position: number;
+  context: string;
+}
+
+export interface GEOQuery {
+  keyword: string;
+  brand: BrandConfig;
+  providers: LLMProvider[];
+}
+
+export interface GEOResult {
+  provider: LLMProvider;
+  keyword: string;
+  mentioned: boolean;
+  position: number | null;
+  sentiment: Sentiment | null;
+  score: number;
+  timestamp: string;
+  contextSnippet?: string;
+  error?: string;
+}
+
+export interface ParsedResponse {
+  mentioned: boolean;
+  position: number | null;
+  sentiment: Sentiment | null;
+  contextSnippet: string | null;
+}
+
+export interface TrackingOptions {
+  fetch?: typeof fetch;
+}
+
+/**
+ * Detects brand mentions in text
+ */
+export function detectMentions(text: string, config: BrandConfig): Mention[] {
+  const mentions: Mention[] = [];
+  const lowerText = text.toLowerCase();
+
+  // Track found positions to avoid duplicates
+  const foundPositions = new Set<number>();
+
+  // Check for exact brand name (case-insensitive)
+  const brandLower = config.brandName.toLowerCase();
+  let searchIndex = 0;
+  while (true) {
+    const idx = lowerText.indexOf(brandLower, searchIndex);
+    if (idx === -1) break;
+
+    if (!foundPositions.has(idx)) {
+      foundPositions.add(idx);
+      const position = calculatePosition(text, idx);
+      mentions.push({
+        type: 'brand',
+        text: text.substring(idx, idx + config.brandName.length),
+        position,
+        context: extractContext(text, idx),
+      });
+    }
+    searchIndex = idx + 1;
+  }
+
+  // Check for domain mentions
+  for (const domain of config.domains) {
+    const domainLower = domain.toLowerCase();
+    searchIndex = 0;
+    while (true) {
+      const idx = lowerText.indexOf(domainLower, searchIndex);
+      if (idx === -1) break;
+
+      if (!foundPositions.has(idx)) {
+        foundPositions.add(idx);
+        const position = calculatePosition(text, idx);
+        mentions.push({
+          type: 'domain',
+          text: text.substring(idx, idx + domain.length),
+          position,
+          context: extractContext(text, idx),
+        });
+      }
+      searchIndex = idx + 1;
+    }
+  }
+
+  // Check for alternative names
+  if (config.alternativeNames) {
+    for (const altName of config.alternativeNames) {
+      const altLower = altName.toLowerCase();
+      searchIndex = 0;
+      while (true) {
+        const idx = lowerText.indexOf(altLower, searchIndex);
+        if (idx === -1) break;
+
+        if (!foundPositions.has(idx)) {
+          foundPositions.add(idx);
+          const position = calculatePosition(text, idx);
+          mentions.push({
+            type: 'alternative',
+            text: text.substring(idx, idx + altName.length),
+            position,
+            context: extractContext(text, idx),
+          });
+        }
+        searchIndex = idx + 1;
+      }
+    }
+  }
+
+  // Sort by position in text
+  mentions.sort((a, b) => a.position - b.position);
+
+  return mentions;
+}
+
+/**
+ * Calculate position (1-indexed) based on list context or sentence order
+ */
+function calculatePosition(text: string, charIndex: number): number {
+  // Check if we're in a numbered list
+  const beforeText = text.substring(0, charIndex);
+  const lines = beforeText.split('\n');
+  const currentLineStart = beforeText.lastIndexOf('\n') + 1;
+  const currentLine = text.substring(currentLineStart).split('\n')[0];
+
+  // Check for numbered list pattern (e.g., "1.", "2.", etc.)
+  const listMatch = currentLine.match(/^(\d+)\./);
+  if (listMatch) {
+    return parseInt(listMatch[1], 10);
+  }
+
+  // Count sentences/items before this mention
+  const sentences = beforeText.split(/[.!?]\s+/);
+  return Math.max(1, sentences.length);
+}
+
+/**
+ * Extract surrounding context for a mention
+ */
+function extractContext(text: string, charIndex: number): string {
+  const contextRadius = 100;
+  const start = Math.max(0, charIndex - contextRadius);
+  const end = Math.min(text.length, charIndex + contextRadius);
+  return text.substring(start, end).trim();
+}
+
+/**
+ * Score a mention based on position, type, and context
+ */
+export function scoreMention(mention: Mention | null): number {
+  if (!mention) return 0;
+
+  let score = 0;
+
+  // Position scoring (first position = highest score)
+  // Position 1 = 50 points, position 2 = 40, position 3 = 30, etc.
+  score += Math.max(0, 60 - mention.position * 10);
+
+  // Type scoring
+  if (mention.type === 'brand') {
+    score += 30;
+  } else if (mention.type === 'alternative') {
+    score += 20;
+  } else if (mention.type === 'domain') {
+    score += 15;
+  }
+
+  // Context scoring - boost for recommendation language
+  const recommendWords = ['recommend', 'best', 'excellent', 'great', 'suggest', 'top choice', 'top pick'];
+  const contextLower = mention.context.toLowerCase();
+  for (const word of recommendWords) {
+    // Use word boundary matching to avoid false positives (e.g., "top" in "Autopilot")
+    const wordRegex = new RegExp(`\\b${word}\\b`, 'i');
+    if (wordRegex.test(contextLower)) {
+      score += 10;
+      break;
+    }
+  }
+
+  return score;
+}
+
+/**
+ * Parse an LLM response to extract mention details
+ */
+export function parseGEOResponse(
+  response: string,
+  config: BrandConfig
+): ParsedResponse {
+  const mentions = detectMentions(response, config);
+
+  if (mentions.length === 0) {
+    return {
+      mentioned: false,
+      position: null,
+      sentiment: null,
+      contextSnippet: null,
+    };
+  }
+
+  // Get the first (most prominent) mention
+  const primaryMention = mentions[0];
+
+  // Determine sentiment from context
+  const sentiment = analyzeSentiment(primaryMention.context);
+
+  // Extract context snippet (max 200 chars)
+  let contextSnippet = primaryMention.context;
+  if (contextSnippet.length > 200) {
+    contextSnippet = contextSnippet.substring(0, 197) + '...';
+  }
+
+  return {
+    mentioned: true,
+    position: primaryMention.position,
+    sentiment,
+    contextSnippet,
+  };
+}
+
+/**
+ * Simple sentiment analysis based on keyword matching
+ */
+function analyzeSentiment(text: string): Sentiment {
+  const lowerText = text.toLowerCase();
+
+  const positiveWords = [
+    'excellent',
+    'great',
+    'best',
+    'recommend',
+    'top',
+    'amazing',
+    'fantastic',
+    'highly',
+    'love',
+    'perfect',
+    'outstanding',
+  ];
+
+  const negativeWords = [
+    'limitation',
+    'limitations',
+    'limited',
+    'not suitable',
+    'not be suitable',
+    'may not',
+    'poor',
+    'bad',
+    'avoid',
+    'issue',
+    'problem',
+    'difficult',
+    'complicated',
+    'expensive',
+    'lack',
+    'lacking',
+    'drawback',
+    'downside',
+  ];
+
+  let positiveScore = 0;
+  let negativeScore = 0;
+
+  for (const word of positiveWords) {
+    if (lowerText.includes(word)) positiveScore++;
+  }
+
+  for (const word of negativeWords) {
+    if (lowerText.includes(word)) negativeScore++;
+  }
+
+  if (positiveScore > negativeScore) return 'positive';
+  if (negativeScore > positiveScore) return 'negative';
+  return 'neutral';
+}
+
+/**
+ * Get the API endpoint for a provider
+ */
+function getProviderEndpoint(provider: LLMProvider): string {
+  switch (provider) {
+    case 'openai':
+      return 'https://api.openai.com/v1/chat/completions';
+    case 'anthropic':
+      return 'https://api.anthropic.com/v1/messages';
+    case 'google':
+      return 'https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent';
+    case 'perplexity':
+      return 'https://api.perplexity.ai/chat/completions';
+    default:
+      throw new Error(`Unknown provider: ${provider}`);
+  }
+}
+
+/**
+ * Query a single LLM provider
+ */
+async function queryProvider(
+  provider: LLMProvider,
+  keyword: string,
+  fetchFn: typeof fetch
+): Promise<string> {
+  const endpoint = getProviderEndpoint(provider);
+
+  const response = await fetchFn(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: provider === 'openai' ? 'gpt-4' : undefined,
+      messages: [
+        {
+          role: 'user',
+          content: keyword,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  // Handle OpenAI/Perplexity response format
+  if (data.choices && data.choices[0]?.message?.content) {
+    return data.choices[0].message.content;
+  }
+
+  // Handle Anthropic response format
+  if (data.content && data.content[0]?.text) {
+    return data.content[0].text;
+  }
+
+  // Handle Google response format
+  if (data.candidates && data.candidates[0]?.content?.parts?.[0]?.text) {
+    return data.candidates[0].content.parts[0].text;
+  }
+
+  throw new Error('Unexpected response format');
+}
+
+/**
+ * Track LLM visibility for a brand across multiple providers
+ */
+export async function trackLLMVisibility(
+  query: GEOQuery,
+  options: TrackingOptions = {}
+): Promise<GEOResult[]> {
+  const fetchFn = options.fetch || fetch;
+  const timestamp = new Date().toISOString();
+
+  // Query all providers in parallel
+  const results = await Promise.all(
+    query.providers.map(async (provider): Promise<GEOResult> => {
+      try {
+        const response = await queryProvider(provider, query.keyword, fetchFn);
+        const parsed = parseGEOResponse(response, query.brand);
+        const mentions = detectMentions(response, query.brand);
+        const score = mentions.length > 0 ? scoreMention(mentions[0]) : 0;
+
+        return {
+          provider,
+          keyword: query.keyword,
+          mentioned: parsed.mentioned,
+          position: parsed.position,
+          sentiment: parsed.sentiment,
+          score,
+          timestamp,
+          contextSnippet: parsed.contextSnippet || undefined,
+        };
+      } catch (error) {
+        return {
+          provider,
+          keyword: query.keyword,
+          mentioned: false,
+          position: null,
+          sentiment: null,
+          score: 0,
+          timestamp,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        };
+      }
+    })
+  );
+
+  return results;
+}

package/src/geo/index.ts

@@ -0,0 +1,10 @@
+/**
+ * GEO (Generative Engine Optimization) Module
+ *
+ * Track brand visibility in LLM responses across providers like
+ * OpenAI, Anthropic, Google, and Perplexity.
+ */
+
+export * from './geo-tracker.js';
+export * from './geo-history.js';
+export * from './geo-content.js';

package/src/git/commit-helper.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  formatConventionalCommit,
+  formatSEOCommitMessage,
+  isGitRepo,
+  detectGitHubPages,
+  generateCommitSummary,
+  COMMIT_TYPES,
+  SEO_SCOPES,
+  type ConventionalCommit,
+  type SEOFixCommit,
+  type CommitConfig,
+} from './commit-helper.js';
+
+describe('commit-helper', () => {
+  describe('formatConventionalCommit', () => {
+    it('formats a basic commit message', () => {
+      const commit: ConventionalCommit = {
+        type: 'fix',
+        description: 'resolve meta tag issue',
+      };
+      expect(formatConventionalCommit(commit)).toBe('fix: resolve meta tag issue');
+    });
+
+    it('includes scope when provided', () => {
+      const commit: ConventionalCommit = {
+        type: 'fix',
+        scope: 'seo',
+        description: 'add missing title tag',
+      };
+      expect(formatConventionalCommit(commit)).toBe('fix(seo): add missing title tag');
+    });
+
+    it('adds breaking change indicator', () => {
+      const commit: ConventionalCommit = {
+        type: 'feat',
+        scope: 'schema',
+        description: 'change JSON-LD format',
+        breaking: true,
+      };
+      expect(formatConventionalCommit(commit)).toBe('feat(schema)!: change JSON-LD format');
+    });
+
+    it('includes body when provided', () => {
+      const commit: ConventionalCommit = {
+        type: 'fix',
+        scope: 'meta',
+        description: 'add meta description',
+        body: 'Added meta descriptions to all pages.\nThis improves SEO score.',
+      };
+      const result = formatConventionalCommit(commit);
+      expect(result).toContain('fix(meta): add meta description');
+      expect(result).toContain('Added meta descriptions to all pages.');
+      expect(result).toContain('This improves SEO score.');
+    });
+
+    it('includes issue codes when provided', () => {
+      const commit: ConventionalCommit = {
+        type: 'fix',
+        scope: 'seo',
+        description: 'fix crawlability issues',
+        issues: ['ROBOTS_TXT_MISSING', 'SITEMAP_MISSING'],
+      };
+      const result = formatConventionalCommit(commit);
+      expect(result).toContain('Issue codes: ROBOTS_TXT_MISSING, SITEMAP_MISSING');
+    });
+  });
+
+  describe('formatSEOCommitMessage', () => {
+    it('formats SEO fix with co-author', () => {
+      const fix: SEOFixCommit = {
+        category: 'on-page',
+        issues: ['TITLE_MISSING', 'META_DESC_MISSING'],
+        filesChanged: ['index.html'],
+        description: 'add on page improvements',
+      };
+      const config: CommitConfig = {
+        systemName: 'SEO Autopilot',
+        systemEmail: 'bot@seo-autopilot.dev',
+      };
+
+      const result = formatSEOCommitMessage(fix, config);
+
+      expect(result).toContain('fix(meta): add on page improvements');
+      expect(result).toContain('Files changed:');
+      expect(result).toContain('- index.html');
+      expect(result).toContain('Issue codes: TITLE_MISSING, META_DESC_MISSING');
+      expect(result).toContain('Co-Authored-By: SEO Autopilot <bot@seo-autopilot.dev>');
+    });
+
+    it('maps categories to correct commit types', () => {
+      const testCases = [
+        { category: 'crawlability', expectedType: 'fix', expectedScope: 'seo' },
+        { category: 'on-page', expectedType: 'fix', expectedScope: 'meta' },
+        { category: 'structured-data', expectedType: 'feat', expectedScope: 'schema' },
+        { category: 'performance', expectedType: 'perf', expectedScope: 'web' },
+        { category: 'social-meta', expectedType: 'feat', expectedScope: 'og' },
+        { category: 'images', expectedType: 'fix', expectedScope: 'images' },
+        { category: 'links', expectedType: 'fix', expectedScope: 'links' },
+        { category: 'security', expectedType: 'fix', expectedScope: 'security' },
+      ];
+
+      testCases.forEach(({ category, expectedType, expectedScope }) => {
+        const fix: SEOFixCommit = {
+          category,
+          issues: ['TEST_ISSUE'],
+          filesChanged: ['test.html'],
+          description: 'test fix',
+        };
+        const result = formatSEOCommitMessage(fix);
+        expect(result).toContain(`${expectedType}(${expectedScope}): test fix`);
+      });
+    });
+
+    it('uses default scope for unknown categories', () => {
+      const fix: SEOFixCommit = {
+        category: 'unknown-category',
+        issues: ['TEST_ISSUE'],
+        filesChanged: ['test.html'],
+        description: 'test fix',
+      };
+      const result = formatSEOCommitMessage(fix);
+      expect(result).toContain('fix(seo): test fix');
+    });
+
+    it('handles multiple files', () => {
+      const fix: SEOFixCommit = {
+        category: 'on-page',
+        issues: ['TEST'],
+        filesChanged: ['index.html', 'about.html', 'contact.html'],
+        description: 'fix meta tags',
+      };
+      const result = formatSEOCommitMessage(fix);
+      expect(result).toContain('- index.html');
+      expect(result).toContain('- about.html');
+      expect(result).toContain('- contact.html');
+    });
+
+    it('uses custom system name and email', () => {
+      const fix: SEOFixCommit = {
+        category: 'on-page',
+        issues: ['TEST'],
+        filesChanged: ['index.html'],
+        description: 'test',
+      };
+      const config: CommitConfig = {
+        systemName: 'Custom Bot',
+        systemEmail: 'custom@example.com',
+      };
+      const result = formatSEOCommitMessage(fix, config);
+      expect(result).toContain('Co-Authored-By: Custom Bot <custom@example.com>');
+    });
+  });
+
+  describe('generateCommitSummary', () => {
+    it('generates summary for successful commits', () => {
+      const commits = [
+        {
+          fix: {
+            category: 'on-page',
+            issues: ['TITLE_MISSING'],
+            filesChanged: ['index.html'],
+            description: 'add title tags',
+          },
+          result: { success: true, hash: 'abc1234' },
+        },
+        {
+          fix: {
+            category: 'social-meta',
+            issues: ['OG_TITLE_MISSING'],
+            filesChanged: ['index.html'],
+            description: 'add og tags',
+          },
+          result: { success: true, hash: 'def5678' },
+        },
+      ];
+
+      const summary = generateCommitSummary(commits);
+
+      expect(summary).toContain('## SEO Fix Commits Summary');
+      expect(summary).toContain('2 commits created');
+      expect(summary).toContain('abc1234');
+      expect(summary).toContain('def5678');
+      expect(summary).toContain('add title tags');
+      expect(summary).toContain('add og tags');
+    });
+
+    it('includes failed commits in summary', () => {
+      const commits = [
+        {
+          fix: {
+            category: 'on-page',
+            issues: ['TITLE_MISSING'],
+            filesChanged: ['index.html'],
+            description: 'add title tags',
+          },
+          result: { success: true, hash: 'abc1234' },
+        },
+        {
+          fix: {
+            category: 'crawlability',
+            issues: ['ROBOTS_TXT_MISSING'],
+            filesChanged: ['robots.txt'],
+            description: 'add robots.txt',
+          },
+          result: { success: false, error: 'Permission denied' },
+        },
+      ];
+
+      const summary = generateCommitSummary(commits);
+
+      expect(summary).toContain('1 commits created');
+      expect(summary).toContain('1 commits failed');
+      expect(summary).toContain('### Failed Commits');
+      expect(summary).toContain('Permission denied');
+    });
+  });
+
+  describe('COMMIT_TYPES and SEO_SCOPES', () => {
+    it('has all expected commit types', () => {
+      const types = COMMIT_TYPES.map((t) => t.type);
+      expect(types).toContain('fix');
+      expect(types).toContain('feat');
+      expect(types).toContain('docs');
+      expect(types).toContain('perf');
+      expect(types).toContain('chore');
+    });
+
+    it('has all expected SEO scopes', () => {
+      expect(SEO_SCOPES).toContain('seo');
+      expect(SEO_SCOPES).toContain('meta');
+      expect(SEO_SCOPES).toContain('og');
+      expect(SEO_SCOPES).toContain('schema');
+      expect(SEO_SCOPES).toContain('images');
+      expect(SEO_SCOPES).toContain('links');
+      expect(SEO_SCOPES).toContain('security');
+    });
+  });
+});
+
+describe('detectGitHubPages', () => {
+  // These tests would need filesystem mocking
+  // For now, we test the function exists and returns expected shape
+  it('returns expected structure', () => {
+    // Test with a non-existent path returns false
+    const result = detectGitHubPages('/non/existent/path');
+    expect(result).toHaveProperty('isGitHubPages');
+    expect(typeof result.isGitHubPages).toBe('boolean');
+  });
+});
+
+describe('isGitRepo', () => {
+  it('returns false for non-git directory', () => {
+    expect(isGitRepo('/tmp')).toBe(false);
+  });
+
+  it('returns boolean', () => {
+    const result = isGitRepo();
+    expect(typeof result).toBe('boolean');
+  });
+});