test(docs): add comprehensive tests and monitoring for llms.txt endpoints

- Add unit tests for middleware rewrites (llms.txt, llms-full.txt, .md)
- Add unit tests for markdown route slug handling
- Create synthetic monitoring script with incident.io integration
- Add GitHub Actions cron workflow for 5-minute health checks
- Configure biome.json to allow console statements in monitoring scripts

The monitoring script checks all configured sites and:
- Sends Slack alerts on failures
- Creates incidents in incident.io when endpoints are down
- Auto-resolves incidents when endpoints recover

Co-Authored-By: [email protected] <[email protected]>

Author: devin-ai-integration[bot]

.github/workflows/monitor-llms-md-endpoints.yml

@@ -0,0 +1,42 @@
+name: Monitor LLM-friendly Docs Endpoints
+
+on:
+  schedule:
+    # Run every 5 minutes
+    - cron: '*/5 * * * *'
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  monitor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: |
+          npm install -g tsx
+          npm install node-fetch
+
+      - name: Run monitoring script
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL_DOCS_INCIDENTS }}
+          INCIDENT_IO_API_KEY: ${{ secrets.INCIDENT_IO_API_KEY }}
+        run: |
+          tsx scripts/monitor/check-llms-md-endpoints.ts
+
+      - name: Report status
+        if: always()
+        run: |
+          if [ $? -eq 0 ]; then
+            echo "✅ All endpoints healthy"
+          else
+            echo "❌ Some endpoints failed - alerts sent"
+          fi

biome.json

@@ -381,7 +381,8 @@
         "packages/workers/proxy/src/websocket.ts",
         "packages/generator-cli/src/**/*.ts",
         "packages/commons/visual-editor-server/src/mongodb-client.ts",
-        "servers/fdr-lambda/src/index.ts"
+        "servers/fdr-lambda/src/index.ts",
+        "scripts/monitor/**/*.ts"
       ],
       "linter": {
         "rules": {

packages/fern-docs/bundle/src/app/[host]/[domain]/[lang]/fern-docs/markdown/route.test.ts

@@ -0,0 +1,59 @@
+import { NextRequest } from "next/server";
+import { describe, expect, it, vi } from "vitest";
+
+describe("markdown route slug handling", () => {
+    const createMockRequest = (pathname: string, searchParams: Record<string, string> = {}) => {
+        const url = new URL(`https://example.com${pathname}`);
+        Object.entries(searchParams).forEach(([key, value]) => {
+            url.searchParams.set(key, value);
+        });
+        return new NextRequest(url);
+    };
+
+    it("should prefer slug from search params over pathname", () => {
+        const request = createMockRequest("/api/fern-docs/markdown", { slug: "docs/quickstart" });
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("docs/quickstart");
+    });
+
+    it("should fallback to pathname parsing when slug param is not present", () => {
+        const request = createMockRequest("/docs/quickstart.md");
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("/docs/quickstart");
+    });
+
+    it("should handle .mdx extension in pathname fallback", () => {
+        const request = createMockRequest("/docs/quickstart.mdx");
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("/docs/quickstart");
+    });
+
+    it("should handle nested paths in slug param", () => {
+        const request = createMockRequest("/api/fern-docs/markdown", {
+            slug: "learn/sdks/overview/quickstart"
+        });
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("learn/sdks/overview/quickstart");
+    });
+
+    it("should handle empty slug param", () => {
+        const request = createMockRequest("/api/fern-docs/markdown", { slug: "" });
+
+        const slugParam = request.nextUrl.searchParams.get("slug");
+        const slug = slugParam ?? request.nextUrl.pathname.replace(/\.(md|mdx)$/, "");
+
+        expect(slug).toBe("");
+    });
+});

packages/fern-docs/bundle/src/middleware.test.ts

@@ -0,0 +1,125 @@
+import { NextRequest } from "next/server";
+import { describe, expect, it } from "vitest";
+
+describe("middleware rewrites", () => {
+    const createMockRequest = (pathname: string, headers: Record<string, string> = {}) => {
+        const url = `https://example.com${pathname}`;
+        return new NextRequest(url, {
+            headers: new Headers(headers)
+        });
+    };
+
+    describe("llms.txt routing", () => {
+        it("should rewrite /llms.txt to /fern-docs/llms.txt with empty slug", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/llms.txt");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms.txt");
+        });
+
+        it("should rewrite /docs/llms.txt to /fern-docs/llms.txt with slug=docs", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/docs/llms.txt");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms.txt");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=docs");
+        });
+
+        it("should rewrite /foo/bar/llms.txt to /fern-docs/llms.txt with slug=foo/bar", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/foo/bar/llms.txt");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms.txt");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=foo%2Fbar");
+        });
+    });
+
+    describe("llms-full.txt routing", () => {
+        it("should rewrite /llms-full.txt to /fern-docs/llms-full.txt with empty slug", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/llms-full.txt");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms-full.txt");
+        });
+
+        it("should rewrite /docs/llms-full.txt to /fern-docs/llms-full.txt with slug=docs", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/docs/llms-full.txt");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms-full.txt");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=docs");
+        });
+    });
+
+    describe("markdown routing", () => {
+        it("should rewrite /page.md to /fern-docs/markdown with slug=page", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/page.md");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/markdown");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=page");
+        });
+
+        it("should rewrite /page.mdx to /fern-docs/markdown with slug=page", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/page.mdx");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/markdown");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=page");
+        });
+
+        it("should rewrite /learn/sdks/overview/quickstart.md to /fern-docs/markdown with correct slug", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/learn/sdks/overview/quickstart.md");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/markdown");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=learn%2Fsdks%2Foverview%2Fquickstart");
+        });
+    });
+
+    describe("content negotiation", () => {
+        it("should rewrite to /fern-docs/llms.txt when Accept header contains text/plain", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/some/page", { accept: "text/plain" });
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms.txt");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=some%2Fpage");
+        });
+
+        it("should rewrite to /fern-docs/llms.txt when Accept header contains text/markdown", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/some/page", { accept: "text/markdown" });
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms.txt");
+            expect(response.headers.get("x-middleware-rewrite")).toContain("slug=some%2Fpage");
+        });
+    });
+
+    describe("legacy /api/fern-docs compatibility", () => {
+        it("should rewrite /api/fern-docs/llms.txt to /fern-docs/llms.txt", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/api/fern-docs/llms.txt");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/llms.txt");
+        });
+
+        it("should rewrite /api/fern-docs/markdown to /fern-docs/markdown", async () => {
+            const { middleware } = await import("./middleware");
+            const request = createMockRequest("/api/fern-docs/markdown");
+            const response = await middleware(request);
+
+            expect(response.headers.get("x-middleware-rewrite")).toContain("/fern-docs/markdown");
+        });
+    });
+});