@rankcli/agent-runtime 0.0.1

package/src/frameworks/recipes/react.yaml

@@ -0,0 +1,202 @@
+# React SEO Recipe
+# Client-side rendering frameworks are notoriously problematic for SEO
+
+framework: react
+display_name: React
+category: spa
+ssr_default: false
+
+seo_challenges:
+  - "Client-side rendering means empty HTML for crawlers"
+  - "Dynamic content invisible to search engines"
+  - "Slow First Contentful Paint"
+  - "No server-side meta tag generation"
+  - "JavaScript-dependent routing breaks crawlability"
+
+checks:
+  # Critical - these will severely hurt SEO
+  - code: REACT_CSR_DETECTED
+    severity: error
+    title: "Client-side rendered React app detected"
+    description: "React apps without SSR send empty HTML to crawlers. Search engines may not index your content."
+    impact: "Critical - your content is likely invisible to Google"
+    howToFix: |
+      Option 1: Migrate to Next.js for automatic SSR/SSG
+      Option 2: Add prerendering with react-snap or prerender.io
+      Option 3: Use react-helmet-async with a prerender service
+    detection:
+      html_patterns:
+        - '<div id="root"></div>'
+        - '<div id="app"></div>'
+      missing_content: true  # Body has minimal text content
+
+  - code: REACT_NO_SSR_META
+    severity: error
+    title: "Meta tags not server-rendered"
+    description: "Title and meta description are set client-side and won't be seen by crawlers."
+    impact: "Search results will show wrong or missing title/description"
+    howToFix: |
+      For Vite/CRA: Use a prerender plugin or migrate to Next.js
+
+      Quick fix with vite-plugin-ssr:
+      ```tsx
+      // pages/+Head.tsx
+      export function Head() {
+        return <>
+          <title>Your Title</title>
+          <meta name="description" content="Your description" />
+        </>
+      }
+      ```
+    detection:
+      title_in_js: true
+      title_not_in_html: true
+
+  - code: REACT_HYDRATION_MISMATCH
+    severity: warning
+    title: "Hydration mismatch detected"
+    description: "Server HTML differs from client render, causing flicker and potential SEO issues."
+    impact: "Can cause content to briefly disappear, confusing crawlers"
+    howToFix: |
+      Common causes:
+      1. Using Date.now() or Math.random() in render
+      2. Browser-only APIs like window.localStorage
+      3. Different data on server vs client
+
+      Fix: Use useEffect for browser-only code:
+      ```tsx
+      const [mounted, setMounted] = useState(false);
+      useEffect(() => setMounted(true), []);
+      if (!mounted) return null; // or skeleton
+      ```
+
+  # Warnings - important but not critical
+  - code: REACT_HELMET_NOT_ASYNC
+    severity: warning
+    title: "Using react-helmet instead of react-helmet-async"
+    description: "react-helmet has memory leaks and doesn't work properly with SSR."
+    howToFix: |
+      Replace react-helmet with react-helmet-async:
+      ```bash
+      npm uninstall react-helmet
+      npm install react-helmet-async
+      ```
+
+      Update imports:
+      ```tsx
+      // Before
+      import { Helmet } from 'react-helmet';
+
+      // After
+      import { Helmet, HelmetProvider } from 'react-helmet-async';
+
+      // Wrap app in provider
+      <HelmetProvider>
+        <App />
+      </HelmetProvider>
+      ```
+
+  - code: REACT_ROUTER_NO_SSR
+    severity: warning
+    title: "React Router without server-side support"
+    description: "Client-side routing breaks when crawlers access URLs directly."
+    howToFix: |
+      Ensure your server returns the same HTML for all routes.
+
+      For static hosting (Netlify, Vercel):
+      Add a redirect rule to serve index.html for all routes.
+
+      netlify.toml:
+      ```toml
+      [[redirects]]
+        from = "/*"
+        to = "/index.html"
+        status = 200
+      ```
+
+  - code: REACT_NO_PRERENDER
+    severity: warning
+    title: "No prerendering configured"
+    description: "Static pages could be prerendered for better SEO and performance."
+    howToFix: |
+      Add react-snap for build-time prerendering:
+      ```bash
+      npm install react-snap
+      ```
+
+      package.json:
+      ```json
+      {
+        "scripts": {
+          "postbuild": "react-snap"
+        },
+        "reactSnap": {
+          "source": "build"
+        }
+      }
+      ```
+
+  # Performance-related
+  - code: REACT_BUNDLE_TOO_LARGE
+    severity: warning
+    title: "React bundle too large"
+    description: "Large JavaScript bundles delay interactivity and hurt Core Web Vitals."
+    howToFix: |
+      1. Use React.lazy() for code splitting:
+      ```tsx
+      const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+
+      <Suspense fallback={<Loading />}>
+        <HeavyComponent />
+      </Suspense>
+      ```
+
+      2. Analyze bundle with source-map-explorer:
+      ```bash
+      npm install source-map-explorer
+      npx source-map-explorer build/static/js/*.js
+      ```
+
+  - code: REACT_NO_SUSPENSE
+    severity: notice
+    title: "Not using Suspense for data fetching"
+    description: "Without Suspense, content pops in causing layout shifts (CLS)."
+    howToFix: |
+      Use Suspense with a data fetching library:
+      ```tsx
+      <Suspense fallback={<Skeleton />}>
+        <DataComponent />
+      </Suspense>
+      ```
+
+performance_tips:
+  - "Use React.memo() for expensive components"
+  - "Lazy load routes with React.lazy()"
+  - "Use useMemo/useCallback to prevent unnecessary rerenders"
+  - "Consider using Preact for smaller bundle size"
+  - "Use production builds (NODE_ENV=production)"
+
+migration_paths:
+  nextjs:
+    effort: medium
+    benefits:
+      - "Automatic SSR/SSG"
+      - "Built-in Image optimization"
+      - "File-based routing"
+      - "API routes"
+    guide: "https://nextjs.org/docs/migrating/from-create-react-app"
+
+  remix:
+    effort: medium
+    benefits:
+      - "Nested routing with data loading"
+      - "Progressive enhancement"
+      - "Better error boundaries"
+    guide: "https://remix.run/docs/en/main/guides/migrating-react-router-app"
+
+  vite-ssr:
+    effort: low
+    benefits:
+      - "Keep existing code"
+      - "Add SSR incrementally"
+    guide: "https://vite-plugin-ssr.com/"

package/src/frameworks/recipes/sveltekit.yaml

@@ -0,0 +1,154 @@
+# SvelteKit SEO Recipe
+# SvelteKit has excellent SSR and SSG support with minimal overhead
+
+framework: sveltekit
+display_name: SvelteKit
+category: meta-framework
+base_framework: svelte
+ssr_default: true
+
+seo_strengths:
+  - "SSR by default"
+  - "Excellent performance (small runtime)"
+  - "Built-in prerendering"
+  - "File-based routing"
+  - "Form actions for progressive enhancement"
+
+checks:
+  - code: SVELTEKIT_NO_LOAD_FUNCTION
+    severity: warning
+    title: "Page without load function"
+    description: "Data fetching in +page.svelte bypasses SSR. Use +page.server.ts or +page.ts."
+    howToFix: |
+      Move data fetching to a load function:
+
+      ```ts
+      // src/routes/products/+page.server.ts
+      export async function load({ fetch }) {
+        const products = await fetch('/api/products').then(r => r.json());
+        return { products };
+      }
+      ```
+
+      ```svelte
+      <!-- src/routes/products/+page.svelte -->
+      <script>
+        export let data;
+      </script>
+
+      {#each data.products as product}
+        <div>{product.name}</div>
+      {/each}
+      ```
+
+  - code: SVELTEKIT_NO_LAYOUT_HEAD
+    severity: warning
+    title: "Missing svelte:head in layout"
+    description: "Common meta tags should be in a layout for consistency."
+    howToFix: |
+      Add svelte:head to your layout:
+
+      ```svelte
+      <!-- src/routes/+layout.svelte -->
+      <script>
+        import { page } from '$app/stores';
+      </script>
+
+      <svelte:head>
+        <title>{$page.data.title ?? 'Your Site'}</title>
+        <meta name="description" content={$page.data.description ?? 'Default description'} />
+        <link rel="canonical" href={$page.url.href} />
+      </svelte:head>
+
+      <slot />
+      ```
+
+  - code: SVELTEKIT_NO_PRERENDER
+    severity: notice
+    title: "Static pages not prerendered"
+    description: "Static pages should be prerendered for best performance."
+    howToFix: |
+      Add prerender to static pages:
+
+      ```ts
+      // src/routes/about/+page.ts
+      export const prerender = true;
+      ```
+
+      Or set default in svelte.config.js:
+      ```js
+      kit: {
+        prerender: {
+          default: true
+        }
+      }
+      ```
+
+  - code: SVELTEKIT_NO_TRAILING_SLASH
+    severity: notice
+    title: "Inconsistent trailing slash handling"
+    description: "Configure trailing slash to avoid duplicate content."
+    howToFix: |
+      Set in svelte.config.js:
+
+      ```js
+      kit: {
+        trailingSlash: 'never' // or 'always'
+      }
+      ```
+
+  - code: SVELTEKIT_ENHANCED_IMAGE
+    severity: notice
+    title: "Not using enhanced images"
+    description: "SvelteKit supports enhanced images with @sveltejs/enhanced-img."
+    howToFix: |
+      Install enhanced images:
+
+      ```bash
+      npm install @sveltejs/enhanced-img
+      ```
+
+      ```svelte
+      <script>
+        import { Image } from '@sveltejs/enhanced-img';
+        import heroImage from '$lib/images/hero.jpg';
+      </script>
+
+      <Image src={heroImage} alt="Hero" />
+      ```
+
+  - code: SVELTEKIT_NO_SITEMAP
+    severity: warning
+    title: "Missing sitemap"
+    description: "Use svelte-sitemap or generate manually."
+    howToFix: |
+      Option 1: Use svelte-sitemap
+      ```bash
+      npm install svelte-sitemap
+      npx svelte-sitemap --domain https://yoursite.com
+      ```
+
+      Option 2: Create src/routes/sitemap.xml/+server.ts:
+      ```ts
+      export async function GET() {
+        const pages = ['/', '/about', '/products'];
+        const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
+          <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+            ${pages.map(page => `
+              <url>
+                <loc>https://yoursite.com${page}</loc>
+              </url>
+            `).join('')}
+          </urlset>`;
+        return new Response(sitemap, {
+          headers: { 'Content-Type': 'application/xml' }
+        });
+      }
+      ```
+
+performance_tips:
+  - "Use load functions for SSR data"
+  - "Prerender static pages"
+  - "Use streaming for slow data sources"
+  - "Leverage Svelte's small runtime"
+  - "Use form actions for progressive enhancement"

package/src/frameworks/recipes/vue.yaml

@@ -0,0 +1,137 @@
+# Vue.js SEO Recipe
+# Similar challenges to React for client-side rendered apps
+
+framework: vue
+display_name: Vue.js
+category: spa
+ssr_default: false
+
+seo_challenges:
+  - "Client-side rendering sends empty HTML to crawlers"
+  - "Vue Router requires proper server configuration"
+  - "Async components delay content rendering"
+  - "No built-in meta tag management"
+
+checks:
+  - code: VUE_CSR_DETECTED
+    severity: error
+    title: "Client-side rendered Vue app detected"
+    description: "Vue apps without SSR send empty HTML to crawlers."
+    impact: "Your content may not be indexed by search engines"
+    howToFix: |
+      Option 1: Migrate to Nuxt for automatic SSR/SSG
+      Option 2: Add SSR with @vue/server-renderer
+      Option 3: Use prerendering with prerender-spa-plugin
+
+      For Nuxt migration, most Vue components work directly.
+
+  - code: VUE_NO_META_MANAGEMENT
+    severity: error
+    title: "No meta tag management library"
+    description: "Title and meta description are not dynamically managed."
+    howToFix: |
+      Install @vueuse/head or vue-meta:
+
+      ```bash
+      npm install @vueuse/head
+      ```
+
+      ```ts
+      // main.ts
+      import { createHead } from '@vueuse/head';
+      const head = createHead();
+      app.use(head);
+      ```
+
+      ```vue
+      <script setup>
+      import { useHead } from '@vueuse/head';
+
+      useHead({
+        title: 'Page Title',
+        meta: [
+          { name: 'description', content: 'Page description' },
+        ],
+      });
+      </script>
+      ```
+
+  - code: VUE_ROUTER_HISTORY_MODE
+    severity: warning
+    title: "Vue Router not in history mode"
+    description: "Hash mode (#/) creates ugly URLs and SEO issues."
+    howToFix: |
+      Use createWebHistory instead of createWebHashHistory:
+
+      ```ts
+      import { createRouter, createWebHistory } from 'vue-router';
+
+      const router = createRouter({
+        history: createWebHistory(),
+        routes: [...],
+      });
+      ```
+
+      Then configure your server to return index.html for all routes.
+
+  - code: VUE_ASYNC_COMPONENT_NO_LOADING
+    severity: warning
+    title: "Async components without loading state"
+    description: "Async components can cause CLS when they pop in."
+    howToFix: |
+      Provide a loading component:
+
+      ```ts
+      import { defineAsyncComponent } from 'vue';
+
+      const AsyncComp = defineAsyncComponent({
+        loader: () => import('./HeavyComponent.vue'),
+        loadingComponent: LoadingSpinner,
+        delay: 200,
+      });
+      ```
+
+  - code: VUE_NO_KEY_ON_LIST
+    severity: notice
+    title: "v-for without :key attribute"
+    description: "Missing keys can cause rendering issues and affect SEO crawling."
+    howToFix: |
+      Always use :key with v-for:
+
+      ```vue
+      <div v-for="item in items" :key="item.id">
+        {{ item.name }}
+      </div>
+      ```
+
+  - code: VUE_TRANSITION_CLS
+    severity: notice
+    title: "Transitions may cause layout shifts"
+    description: "CSS transitions that change element size cause CLS."
+    howToFix: |
+      Use transform instead of width/height changes:
+
+      ```css
+      /* Bad - causes CLS */
+      .fade-enter-active { height: 0 to 100px; }
+
+      /* Good - no CLS */
+      .fade-enter-active { transform: scaleY(0) to scaleY(1); }
+      ```
+
+performance_tips:
+  - "Use Vite for faster development and optimized builds"
+  - "Lazy load routes with dynamic imports"
+  - "Use v-once for static content"
+  - "Use v-memo for expensive list items"
+  - "Consider Nuxt for SSR/SSG"
+
+migration_paths:
+  nuxt:
+    effort: low
+    benefits:
+      - "Automatic SSR/SSG"
+      - "File-based routing"
+      - "Auto-imports"
+      - "Built-in SEO utilities"
+    guide: "https://nuxt.com/docs/migration/overview"

package/src/frameworks/recipes/wordpress.yaml

@@ -0,0 +1,209 @@
+# WordPress SEO Recipe
+# WordPress powers 40%+ of the web - SEO is well-supported with plugins
+
+framework: wordpress
+display_name: WordPress
+category: cms
+ssr_default: true  # PHP renders on server
+
+seo_strengths:
+  - "Server-rendered HTML by default"
+  - "Mature SEO plugin ecosystem"
+  - "Built-in canonical URL support"
+  - "Sitemap generation via plugins"
+  - "Structured data plugins available"
+
+seo_challenges:
+  - "Plugin bloat can slow performance"
+  - "Default themes often lack optimization"
+  - "Image optimization requires plugins"
+  - "Caching needed for performance"
+
+checks:
+  - code: WORDPRESS_NO_SEO_PLUGIN
+    severity: warning
+    title: "No SEO plugin detected"
+    description: "WordPress benefits greatly from an SEO plugin like Yoast or Rank Math."
+    howToFix: |
+      Install an SEO plugin:
+
+      **Yoast SEO** (most popular):
+      1. Go to Plugins > Add New
+      2. Search "Yoast SEO"
+      3. Install and activate
+
+      **Rank Math** (feature-rich free tier):
+      1. Go to Plugins > Add New
+      2. Search "Rank Math"
+      3. Install and activate
+
+      Both provide:
+      - Meta title/description management
+      - XML sitemap generation
+      - Schema markup
+      - Content analysis
+
+  - code: WORDPRESS_OUTDATED
+    severity: error
+    title: "WordPress core is outdated"
+    description: "Running outdated WordPress is a security risk and may have SEO bugs."
+    howToFix: |
+      Update WordPress:
+      1. Backup your site first
+      2. Go to Dashboard > Updates
+      3. Click "Update Now"
+
+      Enable auto-updates in wp-config.php:
+      ```php
+      define('WP_AUTO_UPDATE_CORE', true);
+      ```
+
+  - code: WORDPRESS_NO_CACHING
+    severity: warning
+    title: "No caching plugin detected"
+    description: "WordPress without caching is slow, hurting Core Web Vitals."
+    howToFix: |
+      Install a caching plugin:
+
+      **WP Super Cache** (simple):
+      - Easy setup, good for most sites
+
+      **W3 Total Cache** (advanced):
+      - More features, steeper learning curve
+
+      **LiteSpeed Cache** (if on LiteSpeed server):
+      - Best performance on compatible hosts
+
+  - code: WORDPRESS_LARGE_IMAGES
+    severity: warning
+    title: "Images not optimized"
+    description: "Large images slow down WordPress significantly."
+    howToFix: |
+      Install an image optimization plugin:
+
+      **ShortPixel** or **Smush**:
+      - Compresses existing images
+      - Optimizes on upload
+      - WebP conversion
+
+      Or use Cloudflare Polish for automatic optimization.
+
+  - code: WORDPRESS_TOO_MANY_PLUGINS
+    severity: warning
+    title: "Too many plugins installed"
+    description: "Each plugin adds overhead. Many sites have 30+ plugins when 10-15 suffice."
+    howToFix: |
+      Audit your plugins:
+      1. Go to Plugins > Installed Plugins
+      2. Deactivate plugins not in use
+      3. Delete deactivated plugins
+      4. Consider consolidating (one SEO plugin, one security plugin)
+
+      Aim for under 20 plugins.
+
+  - code: WORDPRESS_NO_LAZY_LOAD
+    severity: notice
+    title: "Native lazy loading not enabled"
+    description: "WordPress 5.5+ has native lazy loading, but themes may disable it."
+    howToFix: |
+      Check if lazy loading is enabled:
+      ```php
+      // In functions.php, remove if present:
+      add_filter('wp_lazy_loading_enabled', '__return_false');
+      ```
+
+      For older WordPress, add:
+      ```php
+      add_filter('wp_lazy_loading_enabled', '__return_true');
+      ```
+
+  - code: WORDPRESS_NO_WEBP
+    severity: notice
+    title: "Not serving WebP images"
+    description: "WebP images are 25-35% smaller than JPEG."
+    howToFix: |
+      Use a plugin that serves WebP:
+
+      1. **ShortPixel**: Auto-converts and serves WebP
+      2. **WebP Express**: Converts and configures server
+
+      Or use Cloudflare with Polish enabled for automatic WebP.
+
+  - code: WORDPRESS_NO_PRELOAD_HINTS
+    severity: notice
+    title: "Missing resource hints"
+    description: "Preload hints can speed up critical resources."
+    howToFix: |
+      Add to your theme's functions.php:
+
+      ```php
+      function add_resource_hints() {
+        // Preload critical font
+        echo '<link rel="preload" href="/wp-content/themes/yourtheme/fonts/main.woff2" as="font" type="font/woff2" crossorigin>';
+
+        // Preconnect to external domains
+        echo '<link rel="preconnect" href="https://fonts.googleapis.com">';
+      }
+      add_action('wp_head', 'add_resource_hints', 1);
+      ```
+
+  - code: WORDPRESS_BLOCKING_SCRIPTS
+    severity: warning
+    title: "Render-blocking scripts detected"
+    description: "JavaScript in <head> blocks rendering."
+    howToFix: |
+      Use a plugin like **Autoptimize** or **Asset CleanUp** to:
+      - Defer JavaScript
+      - Inline critical CSS
+      - Combine files
+
+      Or add defer manually in functions.php:
+      ```php
+      function defer_scripts($tag, $handle) {
+        if (is_admin()) return $tag;
+        return str_replace(' src', ' defer src', $tag);
+      }
+      add_filter('script_loader_tag', 'defer_scripts', 10, 2);
+      ```
+
+  - code: WORDPRESS_NO_SCHEMA
+    severity: warning
+    title: "No structured data detected"
+    description: "Schema markup helps with rich snippets."
+    howToFix: |
+      **If using Yoast/Rank Math**: Schema is included.
+
+      **Manual schema** in theme:
+      ```php
+      function add_organization_schema() {
+        if (is_front_page()) {
+          echo '<script type="application/ld+json">
+          {
+            "@context": "https://schema.org",
+            "@type": "Organization",
+            "name": "Your Company",
+            "url": "' . home_url() . '"
+          }
+          </script>';
+        }
+      }
+      add_action('wp_footer', 'add_organization_schema');
+      ```
+
+performance_tips:
+  - "Use a quality managed WordPress host (WP Engine, Kinsta)"
+  - "Enable object caching (Redis/Memcached)"
+  - "Use a CDN (Cloudflare, Fastly)"
+  - "Keep plugins under 20"
+  - "Choose a lightweight theme (GeneratePress, Astra)"
+  - "Disable unnecessary features (emojis, embeds)"
+
+recommended_plugins:
+  seo:
+    - "Yoast SEO or Rank Math"
+  performance:
+    - "WP Super Cache or LiteSpeed Cache"
+    - "ShortPixel or Smush (images)"
+    - "Autoptimize (JS/CSS)"
+  security:
+    - "Wordfence or Sucuri"