@rankcli/agent-runtime 0.0.1

package/src/frameworks/detector.ts

@@ -0,0 +1,371 @@
+/**
+ * Framework Detection
+ *
+ * Detects web frameworks from:
+ * 1. HTML signatures (data attributes, meta tags, scripts)
+ * 2. package.json dependencies
+ * 3. File structure patterns
+ */
+
+export type Framework =
+  | 'react'
+  | 'nextjs'
+  | 'vue'
+  | 'nuxt'
+  | 'angular'
+  | 'svelte'
+  | 'sveltekit'
+  | 'astro'
+  | 'remix'
+  | 'gatsby'
+  | 'rails'
+  | 'laravel'
+  | 'django'
+  | 'wordpress'
+  | 'unknown';
+
+export interface FrameworkInfo {
+  framework: Framework;
+  version?: string;
+  confidence: 'high' | 'medium' | 'low';
+  detected_from: 'html' | 'package.json' | 'files' | 'headers';
+  meta_framework?: Framework; // e.g., Next.js for React
+}
+
+interface HtmlSignature {
+  framework: Framework;
+  patterns: RegExp[];
+  confidence: 'high' | 'medium' | 'low';
+}
+
+const HTML_SIGNATURES: HtmlSignature[] = [
+  // Next.js
+  {
+    framework: 'nextjs',
+    patterns: [
+      /__next/,
+      /_next\//,
+      /data-nscript/,
+      /__NEXT_DATA__/,
+      /next\/script/,
+    ],
+    confidence: 'high',
+  },
+  // Nuxt
+  {
+    framework: 'nuxt',
+    patterns: [
+      /__nuxt/,
+      /_nuxt\//,
+      /data-n-head/,
+      /nuxt-link/,
+      /__NUXT__/,
+    ],
+    confidence: 'high',
+  },
+  // Gatsby
+  {
+    framework: 'gatsby',
+    patterns: [
+      /___gatsby/,
+      /gatsby-/,
+      /gatsby-image/,
+      /data-gatsby/,
+    ],
+    confidence: 'high',
+  },
+  // Astro
+  {
+    framework: 'astro',
+    patterns: [
+      /astro-/,
+      /data-astro/,
+      /_astro\//,
+    ],
+    confidence: 'high',
+  },
+  // SvelteKit
+  {
+    framework: 'sveltekit',
+    patterns: [
+      /__sveltekit/,
+      /_app\/immutable/,
+      /svelte-kit/,
+    ],
+    confidence: 'high',
+  },
+  // Svelte (standalone)
+  {
+    framework: 'svelte',
+    patterns: [
+      /svelte-\w+/,
+      /__svelte/,
+    ],
+    confidence: 'medium',
+  },
+  // Remix
+  {
+    framework: 'remix',
+    patterns: [
+      /__remix/,
+      /remix-/,
+      /data-remix/,
+    ],
+    confidence: 'high',
+  },
+  // React (generic - lower priority than Next/Gatsby/Remix)
+  {
+    framework: 'react',
+    patterns: [
+      /data-reactroot/,
+      /data-react-helmet/,
+      /_react/,
+      /react-app/,
+    ],
+    confidence: 'medium',
+  },
+  // Vue (generic - lower priority than Nuxt)
+  {
+    framework: 'vue',
+    patterns: [
+      /data-v-[a-f0-9]+/,
+      /v-cloak/,
+      /__vue/,
+    ],
+    confidence: 'medium',
+  },
+  // Angular
+  {
+    framework: 'angular',
+    patterns: [
+      /ng-version/,
+      /_ngcontent/,
+      /ng-\w+=/,
+      /\[ng/,
+    ],
+    confidence: 'high',
+  },
+  // WordPress
+  {
+    framework: 'wordpress',
+    patterns: [
+      /wp-content/,
+      /wp-includes/,
+      /wp-json/,
+      /wordpress/i,
+    ],
+    confidence: 'high',
+  },
+  // Laravel
+  {
+    framework: 'laravel',
+    patterns: [
+      /laravel_session/,
+      /XSRF-TOKEN/,
+      /@csrf/,
+    ],
+    confidence: 'medium',
+  },
+  // Rails
+  {
+    framework: 'rails',
+    patterns: [
+      /csrf-token/,
+      /turbolinks/,
+      /data-turbo/,
+      /rails-ujs/,
+    ],
+    confidence: 'medium',
+  },
+  // Django
+  {
+    framework: 'django',
+    patterns: [
+      /csrfmiddlewaretoken/,
+      /django/,
+    ],
+    confidence: 'medium',
+  },
+];
+
+interface PackageDependency {
+  framework: Framework;
+  packages: string[];
+  meta_framework?: Framework;
+}
+
+const PACKAGE_DEPENDENCIES: PackageDependency[] = [
+  { framework: 'nextjs', packages: ['next'], meta_framework: 'react' },
+  { framework: 'gatsby', packages: ['gatsby'], meta_framework: 'react' },
+  { framework: 'remix', packages: ['@remix-run/react', '@remix-run/node'], meta_framework: 'react' },
+  { framework: 'nuxt', packages: ['nuxt', 'nuxt3'], meta_framework: 'vue' },
+  { framework: 'sveltekit', packages: ['@sveltejs/kit'], meta_framework: 'svelte' },
+  { framework: 'astro', packages: ['astro'] },
+  { framework: 'react', packages: ['react', 'react-dom'] },
+  { framework: 'vue', packages: ['vue'] },
+  { framework: 'angular', packages: ['@angular/core'] },
+  { framework: 'svelte', packages: ['svelte'] },
+];
+
+/**
+ * Detect framework from HTML content
+ */
+export function detectFromHtml(html: string): FrameworkInfo | null {
+  for (const signature of HTML_SIGNATURES) {
+    for (const pattern of signature.patterns) {
+      if (pattern.test(html)) {
+        return {
+          framework: signature.framework,
+          confidence: signature.confidence,
+          detected_from: 'html',
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect framework from package.json content
+ */
+export function detectFromPackageJson(packageJson: {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}): FrameworkInfo | null {
+  const allDeps = {
+    ...packageJson.dependencies,
+    ...packageJson.devDependencies,
+  };
+
+  for (const dep of PACKAGE_DEPENDENCIES) {
+    for (const pkg of dep.packages) {
+      if (allDeps[pkg]) {
+        return {
+          framework: dep.framework,
+          version: allDeps[pkg],
+          confidence: 'high',
+          detected_from: 'package.json',
+          meta_framework: dep.meta_framework,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detect framework from HTTP response headers
+ */
+export function detectFromHeaders(headers: Record<string, string>): FrameworkInfo | null {
+  const poweredBy = headers['x-powered-by']?.toLowerCase() || '';
+  const server = headers['server']?.toLowerCase() || '';
+
+  if (poweredBy.includes('next.js') || poweredBy.includes('next')) {
+    return { framework: 'nextjs', confidence: 'high', detected_from: 'headers' };
+  }
+  if (poweredBy.includes('nuxt')) {
+    return { framework: 'nuxt', confidence: 'high', detected_from: 'headers' };
+  }
+  if (poweredBy.includes('express') || poweredBy.includes('koa')) {
+    // Node.js but unclear which framework
+    return null;
+  }
+  if (poweredBy.includes('php') || server.includes('php')) {
+    // Could be WordPress or Laravel
+    return null;
+  }
+  if (poweredBy.includes('phusion') || poweredBy.includes('passenger')) {
+    return { framework: 'rails', confidence: 'medium', detected_from: 'headers' };
+  }
+
+  return null;
+}
+
+/**
+ * Combined detection using multiple sources
+ */
+export function detectFramework(options: {
+  html?: string;
+  packageJson?: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  headers?: Record<string, string>;
+  files?: string[];
+}): FrameworkInfo {
+  // Try package.json first (most reliable)
+  if (options.packageJson) {
+    const result = detectFromPackageJson(options.packageJson);
+    if (result) return result;
+  }
+
+  // Try headers
+  if (options.headers) {
+    const result = detectFromHeaders(options.headers);
+    if (result) return result;
+  }
+
+  // Try HTML signatures
+  if (options.html) {
+    const result = detectFromHtml(options.html);
+    if (result) return result;
+  }
+
+  // Check file patterns
+  if (options.files) {
+    if (options.files.some(f => f.includes('next.config'))) {
+      return { framework: 'nextjs', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f.includes('nuxt.config'))) {
+      return { framework: 'nuxt', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f.includes('astro.config'))) {
+      return { framework: 'astro', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f.includes('svelte.config'))) {
+      return { framework: 'sveltekit', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f.includes('angular.json'))) {
+      return { framework: 'angular', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f.includes('gatsby-config'))) {
+      return { framework: 'gatsby', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f === 'wp-config.php')) {
+      return { framework: 'wordpress', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f === 'artisan')) {
+      return { framework: 'laravel', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f === 'manage.py')) {
+      return { framework: 'django', confidence: 'high', detected_from: 'files' };
+    }
+    if (options.files.some(f => f === 'Gemfile') && options.files.some(f => f.includes('config/routes.rb'))) {
+      return { framework: 'rails', confidence: 'high', detected_from: 'files' };
+    }
+  }
+
+  return { framework: 'unknown', confidence: 'low', detected_from: 'html' };
+}
+
+/**
+ * Get human-readable framework name
+ */
+export function getFrameworkDisplayName(framework: Framework): string {
+  const names: Record<Framework, string> = {
+    react: 'React',
+    nextjs: 'Next.js',
+    vue: 'Vue.js',
+    nuxt: 'Nuxt',
+    angular: 'Angular',
+    svelte: 'Svelte',
+    sveltekit: 'SvelteKit',
+    astro: 'Astro',
+    remix: 'Remix',
+    gatsby: 'Gatsby',
+    rails: 'Ruby on Rails',
+    laravel: 'Laravel',
+    django: 'Django',
+    wordpress: 'WordPress',
+    unknown: 'Unknown',
+  };
+  return names[framework];
+}

package/src/frameworks/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Framework Detection and SEO Recipes
+ *
+ * Provides framework-specific SEO suggestions for:
+ * - React, Next.js, Gatsby, Remix
+ * - Vue, Nuxt
+ * - Angular
+ * - Svelte, SvelteKit
+ * - Astro
+ * - Ruby on Rails
+ * - Laravel, Django
+ * - WordPress
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import { detectFramework, getFrameworkIssues } from './frameworks';
+ *
+ * // Detect framework from HTML
+ * const frameworkInfo = detectFramework({ html });
+ *
+ * // Get framework-specific issues
+ * const issues = await getFrameworkIssues(frameworkInfo, html, url);
+ * ```
+ */
+
+export {
+  type Framework,
+  type FrameworkInfo,
+  detectFramework,
+  detectFromHtml,
+  detectFromPackageJson,
+  detectFromHeaders,
+  getFrameworkDisplayName,
+} from './detector.js';
+
+export {
+  type FrameworkCheck,
+  type FrameworkRecipe,
+  loadRecipe,
+  getFrameworkIssues,
+  getFrameworkSuggestions,
+  getFrameworkChecks,
+  getPerformanceTips,
+  getSeoChallenges,
+  getMigrationPaths,
+  getTotalFrameworkChecks,
+  getFrameworkSummary,
+  embedRecipe,
+} from './suggestion-engine.js';
+
+// Convenience function to get all available frameworks
+export const SUPPORTED_FRAMEWORKS = [
+  'react',
+  'nextjs',
+  'vue',
+  'nuxt',
+  'angular',
+  'svelte',
+  'sveltekit',
+  'astro',
+  'remix',
+  'gatsby',
+  'rails',
+  'laravel',
+  'django',
+  'wordpress',
+] as const;

package/src/frameworks/recipes/angular.yaml

@@ -0,0 +1,171 @@
+# Angular SEO Recipe
+# Angular has SSR support via Angular Universal
+
+framework: angular
+display_name: Angular
+category: spa
+ssr_default: false
+
+seo_challenges:
+  - "Client-side rendering by default"
+  - "Heavy initial bundle size"
+  - "Complex SSR setup (Angular Universal)"
+  - "Zone.js can cause performance issues"
+
+checks:
+  - code: ANGULAR_NO_UNIVERSAL
+    severity: error
+    title: "Angular app without Universal (SSR)"
+    description: "Client-side Angular apps send empty HTML to crawlers."
+    impact: "Your content may not be indexed by search engines"
+    howToFix: |
+      Add Angular Universal for SSR:
+
+      ```bash
+      ng add @angular/ssr
+      ```
+
+      This adds server-side rendering to your Angular app.
+
+  - code: ANGULAR_NO_TITLE_SERVICE
+    severity: error
+    title: "Not using Title/Meta services"
+    description: "Angular has built-in services for managing title and meta tags."
+    howToFix: |
+      Use Title and Meta services:
+
+      ```ts
+      import { Title, Meta } from '@angular/platform-browser';
+
+      @Component({...})
+      export class ProductComponent {
+        constructor(
+          private title: Title,
+          private meta: Meta
+        ) {}
+
+        ngOnInit() {
+          this.title.setTitle('Product Name | Your Site');
+          this.meta.updateTag({ name: 'description', content: 'Product description' });
+          this.meta.updateTag({ property: 'og:title', content: 'Product Name' });
+        }
+      }
+      ```
+
+  - code: ANGULAR_LAZY_LOAD_MISSING
+    severity: warning
+    title: "Routes not lazy loaded"
+    description: "Loading all modules upfront increases initial bundle size."
+    howToFix: |
+      Use lazy loading for routes:
+
+      ```ts
+      const routes: Routes = [
+        {
+          path: 'products',
+          loadChildren: () => import('./products/products.module')
+            .then(m => m.ProductsModule)
+        },
+        // Or with standalone components
+        {
+          path: 'about',
+          loadComponent: () => import('./about/about.component')
+            .then(m => m.AboutComponent)
+        }
+      ];
+      ```
+
+  - code: ANGULAR_PRERENDER_MISSING
+    severity: warning
+    title: "Static routes not prerendered"
+    description: "Static pages should be prerendered at build time."
+    howToFix: |
+      Configure prerendering in angular.json:
+
+      ```json
+      {
+        "projects": {
+          "your-app": {
+            "architect": {
+              "prerender": {
+                "options": {
+                  "routes": ["/", "/about", "/contact"]
+                }
+              }
+            }
+          }
+        }
+      }
+      ```
+
+      Run: `ng run your-app:prerender`
+
+  - code: ANGULAR_CHANGE_DETECTION
+    severity: notice
+    title: "Using default change detection"
+    description: "OnPush change detection improves performance significantly."
+    howToFix: |
+      Use OnPush for components:
+
+      ```ts
+      @Component({
+        selector: 'app-product',
+        changeDetection: ChangeDetectionStrategy.OnPush,
+        template: `...`
+      })
+      export class ProductComponent {}
+      ```
+
+  - code: ANGULAR_LARGE_BUNDLE
+    severity: warning
+    title: "Large initial bundle detected"
+    description: "Bundle over 500KB significantly hurts performance."
+    howToFix: |
+      1. Enable build optimizer:
+      ```json
+      // angular.json
+      "optimization": true,
+      "buildOptimizer": true
+      ```
+
+      2. Analyze bundle:
+      ```bash
+      ng build --stats-json
+      npx webpack-bundle-analyzer dist/your-app/stats.json
+      ```
+
+      3. Remove unused dependencies
+
+  - code: ANGULAR_NO_IMAGE_DIRECTIVE
+    severity: notice
+    title: "Not using NgOptimizedImage"
+    description: "Angular 15+ has built-in image optimization."
+    howToFix: |
+      Use NgOptimizedImage directive:
+
+      ```ts
+      import { NgOptimizedImage } from '@angular/common';
+
+      @Component({
+        imports: [NgOptimizedImage],
+        template: `
+          <img ngSrc="/hero.jpg" width="1200" height="630" priority />
+        `
+      })
+      ```
+
+performance_tips:
+  - "Use standalone components to reduce bundle"
+  - "Enable OnPush change detection"
+  - "Lazy load routes"
+  - "Use trackBy with ngFor"
+  - "Prerender static pages"
+
+migration_paths:
+  analog:
+    effort: medium
+    benefits:
+      - "File-based routing"
+      - "Full SSR support"
+      - "Vite-powered builds"
+    guide: "https://analogjs.org/docs/introduction"