@rankcli/agent-runtime 0.0.1

package/src/frameworks/recipes/nextjs.yaml

@@ -0,0 +1,268 @@
+# Next.js SEO Recipe
+# Next.js has excellent SEO by default, but there are still common mistakes
+
+framework: nextjs
+display_name: Next.js
+category: meta-framework
+base_framework: react
+ssr_default: true
+
+seo_strengths:
+  - "Server-side rendering by default"
+  - "Static site generation support"
+  - "Built-in Image component with optimization"
+  - "Automatic code splitting"
+  - "File-based routing"
+  - "Built-in metadata API (App Router)"
+
+checks:
+  # App Router specific
+  - code: NEXTJS_NO_METADATA_API
+    severity: warning
+    title: "Not using Next.js Metadata API"
+    description: "Next.js 13+ has a built-in Metadata API that's better than react-helmet."
+    howToFix: |
+      Use the Metadata API in your layout or page:
+
+      ```tsx
+      // app/page.tsx
+      import { Metadata } from 'next';
+
+      export const metadata: Metadata = {
+        title: 'Page Title',
+        description: 'Page description',
+        openGraph: {
+          title: 'OG Title',
+          description: 'OG Description',
+          images: ['/og-image.jpg'],
+        },
+      };
+
+      // For dynamic metadata
+      export async function generateMetadata({ params }): Promise<Metadata> {
+        const product = await getProduct(params.id);
+        return {
+          title: product.name,
+          description: product.description,
+        };
+      }
+      ```
+    app_router_only: true
+
+  - code: NEXTJS_GENERATESTATICPARAMS_MISSING
+    severity: warning
+    title: "Dynamic routes without generateStaticParams"
+    description: "Dynamic routes like [id] should pre-generate static pages for SEO."
+    howToFix: |
+      Add generateStaticParams to pre-render dynamic pages:
+
+      ```tsx
+      // app/products/[id]/page.tsx
+      export async function generateStaticParams() {
+        const products = await getProducts();
+        return products.map((product) => ({
+          id: product.id.toString(),
+        }));
+      }
+      ```
+    app_router_only: true
+
+  # Pages Router specific
+  - code: NEXTJS_NO_GETSTATICPROPS
+    severity: warning
+    title: "Pages without getStaticProps/getServerSideProps"
+    description: "Pages fetching data client-side miss SEO benefits of SSR/SSG."
+    howToFix: |
+      Move data fetching to getStaticProps (for static) or getServerSideProps (for dynamic):
+
+      ```tsx
+      // pages/products.tsx
+      export async function getStaticProps() {
+        const products = await fetchProducts();
+        return {
+          props: { products },
+          revalidate: 3600, // ISR: regenerate every hour
+        };
+      }
+      ```
+    pages_router_only: true
+
+  # Common issues
+  - code: NEXTJS_IMAGE_NOT_USED
+    severity: warning
+    title: "Using <img> instead of next/image"
+    description: "The next/image component provides automatic optimization, lazy loading, and prevents CLS."
+    howToFix: |
+      Replace <img> with next/image:
+
+      ```tsx
+      import Image from 'next/image';
+
+      // Before
+      <img src="/hero.jpg" alt="Hero" />
+
+      // After
+      <Image
+        src="/hero.jpg"
+        alt="Hero"
+        width={1200}
+        height={630}
+        priority // for above-the-fold images
+      />
+      ```
+
+  - code: NEXTJS_NO_PRIORITY_IMAGE
+    severity: notice
+    title: "LCP image missing priority prop"
+    description: "The largest image above the fold should have priority={true} for faster LCP."
+    howToFix: |
+      Add priority to your hero/LCP image:
+
+      ```tsx
+      <Image
+        src="/hero.jpg"
+        alt="Hero"
+        width={1200}
+        height={630}
+        priority
+      />
+      ```
+
+  - code: NEXTJS_LINK_NO_PREFETCH
+    severity: notice
+    title: "Link without prefetch consideration"
+    description: "Next.js prefetches all links by default, which can waste bandwidth."
+    howToFix: |
+      Disable prefetch for less important links:
+
+      ```tsx
+      <Link href="/terms" prefetch={false}>
+        Terms of Service
+      </Link>
+      ```
+
+  - code: NEXTJS_NO_ROBOTS_TXT
+    severity: warning
+    title: "Missing robots.txt configuration"
+    description: "Next.js can generate robots.txt automatically."
+    howToFix: |
+      App Router - create app/robots.ts:
+      ```tsx
+      import { MetadataRoute } from 'next';
+
+      export default function robots(): MetadataRoute.Robots {
+        return {
+          rules: {
+            userAgent: '*',
+            allow: '/',
+            disallow: '/api/',
+          },
+          sitemap: 'https://yoursite.com/sitemap.xml',
+        };
+      }
+      ```
+
+      Pages Router - create public/robots.txt or use next-sitemap package.
+
+  - code: NEXTJS_NO_SITEMAP
+    severity: warning
+    title: "Missing sitemap configuration"
+    description: "Next.js can generate sitemaps automatically."
+    howToFix: |
+      App Router - create app/sitemap.ts:
+      ```tsx
+      import { MetadataRoute } from 'next';
+
+      export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+        const products = await getProducts();
+
+        return [
+          { url: 'https://yoursite.com', lastModified: new Date() },
+          { url: 'https://yoursite.com/about', lastModified: new Date() },
+          ...products.map((product) => ({
+            url: `https://yoursite.com/products/${product.id}`,
+            lastModified: product.updatedAt,
+          })),
+        ];
+      }
+      ```
+
+  - code: NEXTJS_USE_CLIENT_OVERUSE
+    severity: warning
+    title: "Overusing 'use client' directive"
+    description: "Too many client components reduces SSR benefits."
+    howToFix: |
+      Keep 'use client' at the leaf level:
+
+      ```tsx
+      // Bad - entire page is client-rendered
+      'use client';
+      export default function Page() { ... }
+
+      // Good - only interactive parts are client
+      // page.tsx (Server Component)
+      import ClientButton from './ClientButton';
+      export default function Page() {
+        return <div>
+          <h1>Server rendered content</h1>
+          <ClientButton /> {/* Only this is client */}
+        </div>
+      }
+      ```
+
+  - code: NEXTJS_FONT_NOT_OPTIMIZED
+    severity: notice
+    title: "Not using next/font for fonts"
+    description: "next/font automatically optimizes fonts and prevents CLS."
+    howToFix: |
+      Use next/font for Google Fonts or local fonts:
+
+      ```tsx
+      import { Inter } from 'next/font/google';
+
+      const inter = Inter({ subsets: ['latin'] });
+
+      export default function RootLayout({ children }) {
+        return (
+          <html lang="en" className={inter.className}>
+            <body>{children}</body>
+          </html>
+        );
+      }
+      ```
+
+  - code: NEXTJS_NO_TRAILING_SLASH_CONFIG
+    severity: notice
+    title: "Inconsistent trailing slash handling"
+    description: "Inconsistent URLs can cause duplicate content issues."
+    howToFix: |
+      Configure trailingSlash in next.config.js:
+
+      ```js
+      module.exports = {
+        trailingSlash: true, // or false
+      };
+      ```
+
+performance_tips:
+  - "Use React Server Components for static content"
+  - "Add priority to LCP images"
+  - "Use next/font for fonts"
+  - "Enable ISR for frequently updated pages"
+  - "Use Route Handlers instead of API routes for server-only logic"
+
+structured_data:
+  - type: "JSON-LD in metadata"
+    example: |
+      ```tsx
+      export const metadata: Metadata = {
+        other: {
+          'script:ld+json': JSON.stringify({
+            '@context': 'https://schema.org',
+            '@type': 'Organization',
+            name: 'Your Company',
+            url: 'https://yoursite.com',
+          }),
+        },
+      };
+      ```

package/src/frameworks/recipes/nuxt.yaml

@@ -0,0 +1,175 @@
+# Nuxt SEO Recipe
+# Nuxt has excellent SEO capabilities, similar to Next.js for Vue
+
+framework: nuxt
+display_name: Nuxt
+category: meta-framework
+base_framework: vue
+ssr_default: true
+
+seo_strengths:
+  - "Universal rendering (SSR) by default"
+  - "Static site generation support"
+  - "Built-in useSeoMeta composable"
+  - "Automatic code splitting"
+  - "File-based routing"
+  - "NuxtImage for image optimization"
+
+checks:
+  - code: NUXT_NO_USESEOMETA
+    severity: warning
+    title: "Not using useSeoMeta composable"
+    description: "Nuxt 3 has built-in SEO meta composables that are cleaner than useHead."
+    howToFix: |
+      Use useSeoMeta for SEO tags:
+
+      ```vue
+      <script setup>
+      useSeoMeta({
+        title: 'Page Title',
+        description: 'Page description',
+        ogTitle: 'OG Title',
+        ogDescription: 'OG Description',
+        ogImage: '/og-image.jpg',
+        twitterCard: 'summary_large_image',
+      });
+      </script>
+      ```
+
+  - code: NUXT_USEFETCH_CLIENT_ONLY
+    severity: warning
+    title: "Data fetching only on client side"
+    description: "Using onMounted for data fetching bypasses SSR benefits."
+    howToFix: |
+      Use useFetch or useAsyncData instead:
+
+      ```vue
+      <script setup>
+      // Bad - client only
+      const data = ref(null);
+      onMounted(async () => {
+        data.value = await $fetch('/api/data');
+      });
+
+      // Good - SSR friendly
+      const { data } = await useFetch('/api/data');
+      </script>
+      ```
+
+  - code: NUXT_NO_NUXT_IMAGE
+    severity: warning
+    title: "Not using NuxtImage for images"
+    description: "@nuxt/image provides automatic optimization and responsive images."
+    howToFix: |
+      Install and use NuxtImage:
+
+      ```bash
+      npx nuxi module add image
+      ```
+
+      ```vue
+      <template>
+        <NuxtImg
+          src="/hero.jpg"
+          alt="Hero"
+          width="1200"
+          height="630"
+          preload
+        />
+      </template>
+      ```
+
+  - code: NUXT_NO_ROBOTS
+    severity: warning
+    title: "Missing robots.txt configuration"
+    description: "Use @nuxtjs/robots module for robots.txt."
+    howToFix: |
+      Install and configure robots module:
+
+      ```bash
+      npm install @nuxtjs/robots
+      ```
+
+      ```ts
+      // nuxt.config.ts
+      export default defineNuxtConfig({
+        modules: ['@nuxtjs/robots'],
+        robots: {
+          rules: [
+            { UserAgent: '*', Allow: '/' },
+            { UserAgent: '*', Disallow: '/api/' },
+          ],
+          sitemap: 'https://yoursite.com/sitemap.xml',
+        },
+      });
+      ```
+
+  - code: NUXT_NO_SITEMAP
+    severity: warning
+    title: "Missing sitemap configuration"
+    description: "Use @nuxtjs/sitemap module for automatic sitemap."
+    howToFix: |
+      Install sitemap module:
+
+      ```bash
+      npm install @nuxtjs/sitemap
+      ```
+
+      ```ts
+      // nuxt.config.ts
+      export default defineNuxtConfig({
+        modules: ['@nuxtjs/sitemap'],
+        sitemap: {
+          hostname: 'https://yoursite.com',
+        },
+      });
+      ```
+
+  - code: NUXT_SPA_MODE
+    severity: error
+    title: "Nuxt running in SPA mode"
+    description: "SPA mode disables SSR, losing SEO benefits."
+    howToFix: |
+      Remove ssr: false from nuxt.config.ts:
+
+      ```ts
+      export default defineNuxtConfig({
+        // Remove this line
+        // ssr: false,
+      });
+      ```
+
+      If you need client-only components, use <ClientOnly>:
+      ```vue
+      <ClientOnly>
+        <BrowserOnlyWidget />
+      </ClientOnly>
+      ```
+
+  - code: NUXT_NO_PRERENDER
+    severity: notice
+    title: "Static pages not pre-rendered"
+    description: "Static pages could be pre-rendered for better performance."
+    howToFix: |
+      Enable route prerendering in nuxt.config.ts:
+
+      ```ts
+      export default defineNuxtConfig({
+        routeRules: {
+          '/about': { prerender: true },
+          '/blog/**': { prerender: true },
+        },
+      });
+      ```
+
+      Or generate a fully static site:
+      ```bash
+      nuxt generate
+      ```
+
+performance_tips:
+  - "Use useLazyFetch for non-critical data"
+  - "Add preload prop to NuxtImg for LCP images"
+  - "Use Nuxt DevTools to identify performance issues"
+  - "Configure image provider for CDN delivery"
+  - "Use route rules for caching strategies"

package/src/frameworks/recipes/rails.yaml

@@ -0,0 +1,188 @@
+# Ruby on Rails SEO Recipe
+# Rails is server-rendered by default, excellent for SEO
+
+framework: rails
+display_name: Ruby on Rails
+category: server-rendered
+ssr_default: true
+
+seo_strengths:
+  - "Server-rendered HTML by default"
+  - "Turbo for fast navigation without SPA"
+  - "Strong conventions reduce mistakes"
+  - "Mature gem ecosystem"
+
+checks:
+  - code: RAILS_NO_META_TAGS_GEM
+    severity: warning
+    title: "Not using meta-tags gem"
+    description: "The meta-tags gem provides a clean API for SEO tags."
+    howToFix: |
+      Add meta-tags to Gemfile:
+
+      ```ruby
+      gem 'meta-tags'
+      ```
+
+      Run `bundle install`, then:
+
+      ```ruby
+      # app/views/layouts/application.html.erb
+      <head>
+        <%= display_meta_tags site: 'Your Site' %>
+      </head>
+      ```
+
+      ```ruby
+      # In controllers or views
+      set_meta_tags title: 'Page Title',
+                    description: 'Page description',
+                    keywords: 'seo, rails'
+      ```
+
+  - code: RAILS_NO_SITEMAP_GEM
+    severity: warning
+    title: "Not using sitemap_generator gem"
+    description: "sitemap_generator creates SEO-friendly sitemaps automatically."
+    howToFix: |
+      Add to Gemfile:
+
+      ```ruby
+      gem 'sitemap_generator'
+      ```
+
+      Generate config:
+      ```bash
+      rails sitemap:install
+      ```
+
+      Configure config/sitemap.rb:
+      ```ruby
+      SitemapGenerator::Sitemap.default_host = "https://yoursite.com"
+
+      SitemapGenerator::Sitemap.create do
+        add '/about', changefreq: 'monthly'
+        Product.find_each do |product|
+          add product_path(product), lastmod: product.updated_at
+        end
+      end
+      ```
+
+      Generate: `rails sitemap:refresh`
+
+  - code: RAILS_NO_CANONICAL
+    severity: warning
+    title: "Missing canonical URLs"
+    description: "Rails apps with multiple URLs for same content need canonicals."
+    howToFix: |
+      Add canonical tag in layout:
+
+      ```erb
+      <!-- Using meta-tags gem -->
+      <%= display_meta_tags canonical: request.original_url %>
+
+      <!-- Or manually -->
+      <link rel="canonical" href="<%= request.original_url.split('?').first %>" />
+      ```
+
+  - code: RAILS_TURBO_BREAKS_CRAWLERS
+    severity: notice
+    title: "Turbo may affect JavaScript-dependent crawlers"
+    description: "Turbo Drive updates pages via JavaScript, which some crawlers may miss."
+    howToFix: |
+      For SEO-critical pages, ensure content is in initial HTML.
+
+      For dynamic content, add data-turbo="false":
+      ```erb
+      <%= link_to 'Critical Page', critical_path, data: { turbo: false } %>
+      ```
+
+      Or disable for specific pages:
+      ```erb
+      <meta name="turbo-visit-control" content="reload">
+      ```
+
+  - code: RAILS_NO_JSON_LD
+    severity: notice
+    title: "No structured data detected"
+    description: "Add JSON-LD for rich snippets."
+    howToFix: |
+      Create a helper:
+
+      ```ruby
+      # app/helpers/seo_helper.rb
+      module SeoHelper
+        def json_ld(data)
+          content_tag :script, data.to_json.html_safe,
+                      type: 'application/ld+json'
+        end
+      end
+      ```
+
+      Use in views:
+      ```erb
+      <%= json_ld({
+        "@context" => "https://schema.org",
+        "@type" => "Product",
+        "name" => @product.name,
+        "description" => @product.description
+      }) %>
+      ```
+
+  - code: RAILS_SLOW_QUERIES
+    severity: warning
+    title: "N+1 queries may slow pages"
+    description: "Slow pages hurt SEO. Use includes/eager_load."
+    howToFix: |
+      Use bullet gem to detect N+1:
+
+      ```ruby
+      # Gemfile
+      gem 'bullet', group: 'development'
+      ```
+
+      Fix with includes:
+      ```ruby
+      # Before (N+1)
+      @posts = Post.all
+      @posts.each { |p| p.author.name }
+
+      # After (2 queries)
+      @posts = Post.includes(:author).all
+      ```
+
+  - code: RAILS_NO_CACHING
+    severity: notice
+    title: "Page caching not configured"
+    description: "Rails caching can dramatically improve response times."
+    howToFix: |
+      Enable caching in production:
+
+      ```ruby
+      # config/environments/production.rb
+      config.action_controller.perform_caching = true
+      config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] }
+      ```
+
+      Use fragment caching:
+      ```erb
+      <% cache @product do %>
+        <%= render @product %>
+      <% end %>
+      ```
+
+performance_tips:
+  - "Use Russian doll caching for nested views"
+  - "Enable asset fingerprinting and CDN"
+  - "Use Turbo for SPA-like experience"
+  - "Profile with rack-mini-profiler"
+  - "Use Postgres for full-text search instead of LIKE"
+
+recommended_gems:
+  seo:
+    - "meta-tags - SEO tag management"
+    - "sitemap_generator - XML sitemaps"
+  performance:
+    - "bullet - N+1 detection"
+    - "rack-mini-profiler - Performance profiling"
+    - "bootsnap - Faster boot times"