nuxt-ai-ready 2.0.1 → 2.2.0

package/dist/runtime/server/db/shared.js

@@ -57,6 +57,18 @@ export function normalizeRoute(route) {
     return "/";
   return route.startsWith("/") ? route : `/${route}`;
 }
+const RE_LIKE_META = /[\\%_]/g;
+export function escapeLikeTerm(term) {
+  return term.replace(RE_LIKE_META, (ch) => `\\${ch}`);
+}
+export function likeSubstring(term) {
+  return `%${escapeLikeTerm(term)}%`;
+}
+export const LIKE_ESCAPE = "\\";
+const MAX_BIND_PARAMS_PER_STATEMENT = 100;
+export function maxRowsPerInsert(paramsPerRow) {
+  return Math.max(1, Math.floor(MAX_BIND_PARAMS_PER_STATEMENT / paramsPerRow));
+}
 export function normalizeRouteKey(route) {
   return normalizeRoute(route).replace(RE_LEADING_SLASH, "").replace(RE_SLASH, ":") || "index";
 }

package/dist/runtime/server/middleware/markdown.js

@@ -1,10 +1,11 @@
 import { createError, defineEventHandler, setHeader, setResponseStatus } from "#nuxtseo/h3";
-import { useNitroApp } from "#nuxtseo/nitro";
+import { useNitroApp, useRuntimeConfig } from "#nuxtseo/nitro";
 import { resolveLocaleAlternateUrl } from "../../i18n-url.js";
 import { logger } from "../logger.js";
 import { computeLocaleAlternates, resolveLocaleFromRoute } from "../utils/i18n.js";
 import { INTERNAL_HEADER } from "../utils/negotiation-decision.js";
 import { applyNegotiation, buildNegotiationContext, decideNegotiation, ensureSiteConfig, setMarkdownHeaders } from "../utils/negotiation-response.js";
+import { appendSitemapSection, isSitemapMdRequest, SITEMAP_MD_ROUTE } from "../utils/sitemap-md.js";
 function notFoundMarkdown(ctx, canonicalUrl, build) {
   const { path, config, resolveUrl, routeContext } = ctx;
   const body = [
@@ -37,6 +38,9 @@ function notFoundMarkdown(ctx, canonicalUrl, build) {
 ${body}`;
 }
 export default defineEventHandler(async (event) => {
+  const runtimeConfig = useRuntimeConfig(event);
+  if (isSitemapMdRequest(event.path, runtimeConfig.app.baseURL, runtimeConfig["nuxt-ai-ready"]?.sitemapMd !== false))
+    return;
   const decision = decideNegotiation(event, "middleware");
   const negotiationResponse = await applyNegotiation(event, decision);
   if (decision._tag !== "render")
@@ -45,6 +49,7 @@ export default defineEventHandler(async (event) => {
   const ctx = buildNegotiationContext(event, decision.path);
   const { path, config, resolvePath, resolveUrl, routeContext } = ctx;
   const canonicalUrl = resolveUrl(path);
+  const finalizeMarkdown = (markdown) => config.sitemapMd === false ? markdown : appendSitemapSection(markdown, resolvePath(SITEMAP_MD_ROUTE));
   const [
     { tryGetContentMarkdown },
     { fetchRawWithEvent },
@@ -65,7 +70,7 @@ export default defineEventHandler(async (event) => {
       last_updated: updatedAt || (/* @__PURE__ */ new Date()).toISOString()
     }, markdown);
     setMarkdownHeaders(event, ctx);
-    return responseMarkdown;
+    return finalizeMarkdown(responseMarkdown);
   }
   const contentPage = await tryGetContentMarkdown(event, path).catch((e) => {
     logger.debug(`[markdown] Content lookup failed for ${path}`, e);
@@ -80,8 +85,8 @@ export default defineEventHandler(async (event) => {
       last_updated: contentPage.updatedAt || (/* @__PURE__ */ new Date()).toISOString()
     });
     setMarkdownHeaders(event, ctx);
-    return `${frontmatter}
-${contentPage.markdown}`;
+    return finalizeMarkdown(`${frontmatter}
+${contentPage.markdown}`);
   }
   logger.debug(`[markdown] Fetching HTML for ${path}`);
   const response = await fetchRawWithEvent(event, resolvePath(path), {
@@ -152,5 +157,5 @@ ${contentPage.markdown}`;
     }
   );
   setMarkdownHeaders(event, ctx);
-  return result.markdown;
+  return finalizeMarkdown(result.markdown);
 });

package/dist/runtime/server/middleware/markdown.prerender.js

@@ -10,6 +10,7 @@ import { buildFrontmatter } from "../utils/frontmatter.js";
 import { extractKeywords } from "../utils/keywords.js";
 import { getMarkdownRenderInfo } from "../utils/markdown-request.js";
 import { consumePrerenderedHtml } from "../utils/prerender-html.js";
+import { isSitemapMdRequest } from "../utils/sitemap-md.js";
 function extractHeadingsFromMarkdown(markdown) {
   const headings = [];
   for (const m of markdown.matchAll(/^(#{1,6}) ([^\n]+)$/gm)) {
@@ -27,11 +28,13 @@ export default defineEventHandler(async (event) => {
   if (!import.meta.prerender) {
     return;
   }
+  const fullRuntimeConfig = useRuntimeConfig(event);
+  if (isSitemapMdRequest(event.path, fullRuntimeConfig.app.baseURL, fullRuntimeConfig["nuxt-ai-ready"]?.sitemapMd !== false))
+    return;
   const renderInfo = getMarkdownRenderInfo(event, { _tag: "prerender" });
   if (!renderInfo || "notAcceptable" in renderInfo)
     return;
   const { path } = renderInfo;
-  const fullRuntimeConfig = useRuntimeConfig(event);
   const runtimeConfig = fullRuntimeConfig["nuxt-ai-ready"];
   const deployedPath = toDeployedRoute(path, fullRuntimeConfig.app.baseURL);
   const canonicalUrl = withSiteUrl(event, deployedPath);

package/dist/runtime/server/plugins/db-lifecycle.js

@@ -1,10 +1,11 @@
-import { DB_CONTEXT_KEY } from "../db/context.js";
+import { DB_CONTEXT_KEY, DB_PROMISE_CONTEXT_KEY, DB_WORK_CONTEXT_KEY } from "../db/context.js";
 export default function dbLifecyclePlugin(nitroApp) {
   nitroApp.hooks.hook("afterResponse", async (event) => {
-    if (!event.context?.[DB_CONTEXT_KEY])
+    if (!event.context?.[DB_CONTEXT_KEY] && !event.context?.[DB_PROMISE_CONTEXT_KEY] && !event.context?.[DB_WORK_CONTEXT_KEY]) {
       return;
-    const { closeDrizzle } = await import("../db/index.js");
-    await closeDrizzle(event);
+    }
+    const { finishDrizzleResponse } = await import("../db/index.js");
+    await finishDrizzleResponse(event);
   });
   nitroApp.hooks.hook("close", async () => {
     const { closeDrizzle } = await import("../db/index.js");

package/dist/runtime/server/plugins/sitemap-seeder.js

@@ -1,4 +1,5 @@
 import { useRuntimeConfig } from "#nuxtseo/nitro";
+import { trackDrizzleWork } from "../db/drizzle/client.js";
 import { getPageLastmods, getSitemapLastCrawledAt, markSitemapSeeded, seedRoutes } from "../db/queries.js";
 import { logger } from "../logger.js";
 import { mapSitemapRoutes } from "../utils/sitemap-routes.js";
@@ -12,6 +13,7 @@ function recordDiagnostic(event, message) {
   list.push(message);
 }
 const SEED_INTERVAL_MS = 5 * 60 * 1e3;
+const lastSeedAt = /* @__PURE__ */ new Map();
 const READ_TIMEOUT_MS = 3e3;
 const SLOW_READ_WARN_MS = 1e3;
 const SLOW_SEED_WARN_MS = 1e4;
@@ -86,9 +88,11 @@ export default function sitemapSeederPlugin(nitroApp) {
       logger.warn(`[sitemap-seeder] ${message} for ${sitemapName}`);
       record?.(message);
     }
-    if (lastCrawled && Date.now() - lastCrawled < SEED_INTERVAL_MS)
+    const lastSeed = Math.max(lastCrawled ?? 0, lastSeedAt.get(sitemapName) ?? 0);
+    if (Date.now() - lastSeed < SEED_INTERVAL_MS)
       return;
-    const routes = [...routeToUrl.keys()];
+    lastSeedAt.set(sitemapName, Date.now());
+    const routes = [...routeToUrl.entries()].map(([route, url]) => ({ route, url: url.loc }));
     const urlCount = urls.length;
     const seed = async () => {
       const seedStart = Date.now();
@@ -106,9 +110,10 @@ export default function sitemapSeederPlugin(nitroApp) {
         logger.debug(`[sitemap-seeder] Seeded ${seeded} routes from ${sitemapName} in ${seedMs}ms`);
     };
     if (event.waitUntil) {
-      event.waitUntil(seed().catch(
+      const backgroundSeed = trackDrizzleWork(event, seed()).catch(
         (err) => logger.error(`[sitemap-seeder] Background seed failed: ${err.message}`)
-      ));
+      );
+      event.waitUntil(backgroundSeed);
     } else {
       await seed();
     }

package/dist/runtime/server/routes/__ai-ready/cron.get.js

@@ -1,7 +1,15 @@
-import { eventHandler } from "#nuxtseo/h3";
+import { createError, eventHandler } from "#nuxtseo/h3";
 import { runCron } from "../../utils/runCron.js";
 export default eventHandler(async (event) => {
   const { requireAuth } = await import("../../utils/auth.js");
   requireAuth(event);
-  return runCron(event);
+  const result = await runCron(event);
+  if (result.failed) {
+    throw createError({
+      statusCode: 500,
+      message: `Cron run failed at the ${result.failed.stage} stage: ${result.failed.message}`,
+      data: result.failed
+    });
+  }
+  return result;
 });

package/dist/runtime/server/routes/__ai-ready/poll.post.js

@@ -1,21 +1,37 @@
-import { eventHandler, getQuery } from "#nuxtseo/h3";
+import { eventHandler, getQuery, setResponseStatus } from "#nuxtseo/h3";
+import { useRuntimeConfig } from "#nuxtseo/nitro";
+import { releaseCronLock, tryAcquireCronLock } from "../../db/queries.js";
+import { logger } from "../../logger.js";
 import { batchIndexPages } from "../../utils/batchIndex.js";
 export default eventHandler(async (event) => {
   const { requireAuth } = await import("../../utils/auth.js");
   requireAuth(event);
+  const lock = await tryAcquireCronLock(event);
+  if (lock._tag === "held") {
+    setResponseStatus(event, 409);
+    return { locked: true };
+  }
   const query = getQuery(event);
-  const limit = query.limit ? Math.max(1, Math.min(50, Math.trunc(Number(query.limit)) || 10)) : void 0;
+  const config = useRuntimeConfig(event)["nuxt-ai-ready"];
+  const defaultLimit = Math.max(1, Math.trunc(Math.min(config.runtimeSync?.batchSize ?? 10, 50))) || 10;
+  const limit = query.limit ? Math.max(1, Math.min(50, Math.trunc(Number(query.limit)) || defaultLimit)) : defaultLimit;
   const timeout = query.timeout ? Math.max(1e3, Math.trunc(Number(query.timeout)) || 3e4) : void 0;
-  const result = await batchIndexPages(event, {
-    limit,
-    all: query.all === "true" || query.all === "1",
-    timeout
-  });
-  return {
-    indexed: result.indexed,
-    remaining: result.remaining,
-    errors: result.errors.length > 0 ? result.errors : void 0,
-    duration: result.duration,
-    complete: result.complete
-  };
+  try {
+    const result = await batchIndexPages(event, {
+      limit,
+      all: query.all === "true" || query.all === "1",
+      timeout
+    });
+    return {
+      indexed: result.indexed,
+      remaining: result.remaining,
+      errors: result.errors.length > 0 ? result.errors : void 0,
+      duration: result.duration,
+      complete: result.complete
+    };
+  } finally {
+    await releaseCronLock(event, lock.token).catch((err) => {
+      logger.warn(`[poll] Failed to release lock: ${err?.message || err}`);
+    });
+  }
 });

package/dist/runtime/server/routes/__ai-ready/reindex.post.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/routes/__ai-ready/reindex.post.js

@@ -0,0 +1,23 @@
+import { createError, eventHandler, getQuery, setResponseStatus } from "#nuxtseo/h3";
+import { indexPageByRoute } from "../../utils/indexPage.js";
+export default eventHandler(async (event) => {
+  const { requireAuth } = await import("../../utils/auth.js");
+  requireAuth(event);
+  const query = getQuery(event);
+  const route = typeof query.route === "string" ? query.route.trim() : "";
+  if (!route.startsWith("/")) {
+    throw createError({ statusCode: 400, message: 'Invalid route. It must be an absolute path starting with "/", for example "/about".' });
+  }
+  const force = query.force !== "false" && query.force !== "0";
+  const result = await indexPageByRoute(route, event, { force });
+  if (!result.success) {
+    setResponseStatus(event, 502);
+    return { route, indexed: false, error: result.error ?? `Failed to index ${route}` };
+  }
+  return {
+    route,
+    indexed: !result.skipped,
+    skipped: result.skipped || void 0,
+    contentChanged: result.contentChanged
+  };
+});

package/dist/runtime/server/routes/api-catalog.js

@@ -1,10 +1,19 @@
-import { assertMethod, defineEventHandler, setHeader } from "#nuxtseo/h3";
+import { assertMethod, createError, defineEventHandler, setHeader, setHeaders, setResponseStatus } from "#nuxtseo/h3";
 import { useRuntimeConfig } from "#nuxtseo/nitro";
 export default defineEventHandler((event) => {
+  setHeader(event, "Access-Control-Allow-Origin", "*");
+  if (event.method === "OPTIONS") {
+    setHeaders(event, {
+      "Access-Control-Allow-Headers": "Content-Type, If-None-Match",
+      "Access-Control-Allow-Methods": "GET, HEAD"
+    });
+    setResponseStatus(event, 204);
+    return null;
+  }
   assertMethod(event, ["GET", "HEAD"]);
   const config = useRuntimeConfig(event)["nuxt-ai-ready"].apiCatalog;
   if (!config)
-    return;
+    throw createError({ statusCode: 404, message: "API catalog is not configured" });
   setHeader(event, "content-type", config.mediaType);
   setHeader(event, "link", `<${config.href}>; rel="api-catalog"`);
   if (event.method === "HEAD")

package/dist/runtime/server/routes/llms.txt.get.js

@@ -1,23 +1,28 @@
 import { eventHandler, setHeader } from "#nuxtseo/h3";
 import { defineCachedFunction, useRuntimeConfig } from "#nuxtseo/nitro";
 import { buildLlmsTxt } from "../../llms-txt-utils.js";
-const buildLlmsTxtCached = defineCachedFunction(
-  buildLlmsTxt,
-  {
-    name: "llms-txt",
-    group: "ai-ready",
-    maxAge: 60 * 10,
-    // 10 minutes
-    swr: true
+const cachedBuilders = /* @__PURE__ */ new Map();
+function getBuildLlmsTxtCached(maxAge) {
+  let cached = cachedBuilders.get(maxAge);
+  if (!cached) {
+    cached = defineCachedFunction(buildLlmsTxt, {
+      name: "llms-txt",
+      group: "ai-ready",
+      maxAge,
+      swr: true
+    });
+    cachedBuilders.set(maxAge, cached);
   }
-);
+  return cached;
+}
 export default eventHandler(async (event) => {
   const runtimeConfig = useRuntimeConfig(event)["nuxt-ai-ready"];
-  const cacheEnabled = !import.meta.dev && runtimeConfig.llmsTxtCacheSeconds > 0;
-  const content = cacheEnabled ? await buildLlmsTxtCached(event) : await buildLlmsTxt(event);
+  const cacheSeconds = runtimeConfig.llmsTxtCacheSeconds;
+  const cacheEnabled = !import.meta.dev && cacheSeconds > 0;
+  const content = cacheEnabled ? await getBuildLlmsTxtCached(cacheSeconds)(event) : await buildLlmsTxt(event);
   setHeader(event, "Content-Type", "text/plain; charset=utf-8");
   if (cacheEnabled) {
-    setHeader(event, "Cache-Control", `public, max-age=${runtimeConfig.llmsTxtCacheSeconds}, s-maxage=${runtimeConfig.llmsTxtCacheSeconds}, stale-while-revalidate=3600`);
+    setHeader(event, "Cache-Control", `public, max-age=${cacheSeconds}, s-maxage=${cacheSeconds}, stale-while-revalidate=3600`);
   }
   return content;
 });

package/dist/runtime/server/routes/sitemap.md.get.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/server/routes/sitemap.md.get.js

@@ -0,0 +1,51 @@
+import { eventHandler, setHeader } from "#nuxtseo/h3";
+import { defineCachedFunction, useRuntimeConfig } from "#nuxtseo/nitro";
+import { getSiteConfig } from "#site-config/server/composables";
+import { toMarkdownPath } from "../../markdown-path.js";
+import { toDeployedRoute } from "../../route-path.js";
+import { queryPages } from "../db/queries.js";
+import { logger } from "../logger.js";
+import { buildSitemapMd } from "../utils/sitemap-md.js";
+async function buildSitemapMarkdown(event) {
+  let pages = [];
+  try {
+    pages = await queryPages(event);
+  } catch (err) {
+    logger.warn(
+      `[ai-ready] Database unavailable for sitemap.md, serving an empty sitemap: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const baseURL = useRuntimeConfig(event).app.baseURL;
+  return buildSitemapMd(
+    pages.map((page) => ({ route: page.route, title: page.title, updatedAt: page.updatedAt })),
+    {
+      siteName: getSiteConfig(event).name,
+      resolveHref: (route) => toDeployedRoute(toMarkdownPath(route), baseURL)
+    }
+  );
+}
+const cachedBuilders = /* @__PURE__ */ new Map();
+function getBuildSitemapMdCached(maxAge) {
+  let cached = cachedBuilders.get(maxAge);
+  if (!cached) {
+    cached = defineCachedFunction(buildSitemapMarkdown, {
+      name: "sitemap-md",
+      group: "ai-ready",
+      maxAge,
+      swr: true
+    });
+    cachedBuilders.set(maxAge, cached);
+  }
+  return cached;
+}
+export default eventHandler(async (event) => {
+  const fullRuntimeConfig = useRuntimeConfig(event);
+  const runtimeConfig = fullRuntimeConfig["nuxt-ai-ready"];
+  const cacheSeconds = runtimeConfig.llmsTxtCacheSeconds ?? 600;
+  const cacheEnabled = !import.meta.dev && cacheSeconds > 0;
+  setHeader(event, "Content-Type", "text/markdown; charset=utf-8");
+  if (cacheEnabled) {
+    setHeader(event, "Cache-Control", `public, max-age=${cacheSeconds}, s-maxage=${cacheSeconds}, stale-while-revalidate=3600`);
+  }
+  return cacheEnabled ? await getBuildSitemapMdCached(cacheSeconds)(event) : await buildSitemapMarkdown(event);
+});

package/dist/runtime/server/tasks/ai-ready-cron.js

@@ -1,4 +1,5 @@
 import { defineTask } from "#nuxtseo/nitro";
+import { logger } from "../logger.js";
 import { runCron } from "../utils/runCron.js";
 export default defineTask({
   meta: {
@@ -11,6 +12,8 @@ export default defineTask({
     const result = await runCron(void 0, {
       batchSize: payload?.limit
     });
+    if (result.failed)
+      logger.error(`[ai-ready:cron] Run failed at the ${result.failed.stage} stage: ${result.failed.message}`);
     return { result };
   }
 });

package/dist/runtime/server/utils/i18n.d.ts

@@ -5,3 +5,7 @@ export type { LocaleAlternate, LocaleAlternateResolution, LocalePages, RouteLoca
 export declare function getRuntimeI18n(aiReadyConfig: {
     i18n?: RuntimeI18nConfig | null;
 }): RuntimeI18nConfig | null;
+/** Normalize a host or URL into a comparable hostname (lowercase, no scheme, no path). */
+export declare function normalizeHost(value: string): string;
+/** True when the host equals a domain configured on any i18n locale. */
+export declare function hostMatchesLocaleDomain(host: string | undefined, i18n: RuntimeI18nConfig): boolean;

package/dist/runtime/server/utils/i18n.js

@@ -7,3 +7,16 @@ export {
 export function getRuntimeI18n(aiReadyConfig) {
   return aiReadyConfig.i18n || null;
 }
+export function normalizeHost(value) {
+  return value.trim().toLowerCase().replace(/^[a-z][a-z\d+.-]*:\/\//, "").split("/")[0];
+}
+export function hostMatchesLocaleDomain(host, i18n) {
+  if (!host)
+    return false;
+  const normalized = normalizeHost(host);
+  if (!normalized)
+    return false;
+  return i18n.locales.some(
+    (locale) => [...locale.domains ?? [], locale.domain, ...locale.defaultForDomains ?? []].some((domain) => domain && normalizeHost(domain) === normalized)
+  );
+}

package/dist/runtime/server/utils/indexPage.d.ts

@@ -1,5 +1,4 @@
 import type { H3Event } from '#nuxtseo/h3';
-export declare const INDEXING_HEADER = "x-ai-ready-indexing";
 export interface IndexPageOptions {
     /** Skip if page was indexed within TTL (uses config ttl if not specified) */
     ttl?: number;

package/dist/runtime/server/utils/indexPage.js

@@ -5,7 +5,7 @@ import { logger } from "../logger.js";
 import { convertHtmlToMarkdown } from "../utils.js";
 import { createUniversalContext } from "./context.js";
 import { extractKeywords } from "./keywords.js";
-export const INDEXING_HEADER = "x-ai-ready-indexing";
+import { INTERNAL_HEADER } from "./negotiation-decision.js";
 export async function indexPage(route, html, options = {}, event) {
   const config = useRuntimeConfig()["nuxt-ai-ready"];
   const ttl = options.ttl ?? config.runtimeSync.ttl;
@@ -70,10 +70,10 @@ export async function indexPage(route, html, options = {}, event) {
 export async function indexPageByRoute(route, event, options = {}) {
   logger.debug(`[indexPageByRoute] Fetching HTML for ${route} (timeout: 10000ms)`);
   const html = await (event ? fetchWithEvent(event, route, {
-    headers: { [INDEXING_HEADER]: "1" },
+    headers: { accept: "text/html", [INTERNAL_HEADER]: "1" },
     timeout: 1e4
   }) : globalThis.$fetch(route, {
-    headers: { [INDEXING_HEADER]: "1" },
+    headers: { accept: "text/html", [INTERNAL_HEADER]: "1" },
     timeout: 1e4
     // 10s timeout per page (must fit within CF worker limit)
   })).catch((err) => {
@@ -98,5 +98,11 @@ export async function indexPageByRoute(route, event, options = {}) {
     }
     return { success: false, error: `Failed to fetch HTML for ${route}` };
   }
-  return indexPage(route, html, options, event);
+  try {
+    return await indexPage(route, html, options, event);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.warn(`[indexPageByRoute] Failed to index ${route}:`, message);
+    return { success: false, error: message || `Failed to index ${route}` };
+  }
 }

package/dist/runtime/server/utils/link-header.d.ts

@@ -8,10 +8,12 @@ import type { RuntimeI18nConfig, RuntimeRouteContext } from './i18n.js';
  */
 export declare function encodePathForHeader(path: string): string;
 type LinkUrlResolver = (path: string) => string;
+export declare const LLMS_TXT_PATH = "/llms.txt";
 interface LinkHeaderConfig {
     apiCatalog?: {
         href: string;
     };
+    describedby?: boolean;
     i18n?: RuntimeI18nConfig | null;
 }
 /**

package/dist/runtime/server/utils/link-header.js

@@ -4,6 +4,7 @@ import { computeLocaleAlternates } from "./i18n.js";
 export function encodePathForHeader(path) {
   return encodeURI(path);
 }
+export const LLMS_TXT_PATH = "/llms.txt";
 function resolveHeaderUrl(path, resolveUrl) {
   if (!resolveUrl)
     return path;
@@ -21,6 +22,11 @@ export function buildLinkHeader(path, variant, config, resolveUrl, routeContext
   } else {
     const href = resolveHeaderUrl(path, resolveUrl);
     parts.push(`<${encodePathForHeader(href)}>; rel="alternate"; type="text/html"`);
+    parts.push(`<${encodePathForHeader(href)}>; rel="canonical"`);
+  }
+  if (config.describedby !== false) {
+    const href = resolveHeaderUrl(LLMS_TXT_PATH, resolveUrl);
+    parts.push(`<${encodePathForHeader(href)}>; rel="describedby"`);
   }
   if (config.i18n) {
     const alternates = computeLocaleAlternates(path, config.i18n, routeContext);

package/dist/runtime/server/utils/markdown-request.js

@@ -1,6 +1,8 @@
 import { negotiateContent } from "@mdream/js/negotiate";
 import { getBotInfo } from "@nuxtjs/robots/util";
 import { getHeaders } from "#nuxtseo/h3";
+import { isReservedPath } from "../../markdown-path.js";
+const RE_MD_EXT = /\.md$/;
 export function toMarkdownRequest(event, isPrerender = !!import.meta.prerender) {
   return { path: event.path, headers: getHeaders(event), isPrerender };
 }
@@ -25,7 +27,7 @@ export function getRequestRenderInfo(request, mode = { _tag: "runtime", contentN
   const queryIndex = request.path.indexOf("?");
   const originalPath = queryIndex === -1 ? request.path : request.path.slice(0, queryIndex);
   const isPrerender = mode._tag === "prerender";
-  if (originalPath.startsWith("/api") || originalPath.startsWith("/_") || originalPath.startsWith("/@"))
+  if (isReservedPath(originalPath.replace(RE_MD_EXT, "")))
     return null;
   const accept = request.headers.accept || "";
   if (!originalPath.endsWith(".md") && accept && /\b(?:application\/json|text\/event-stream)\b/i.test(accept) && !/text\/(?:html|markdown|plain)\b|\*\/\*/i.test(accept)) {

package/dist/runtime/server/utils/negotiation-decision.d.ts

@@ -1,7 +1,7 @@
 import type { ContentNegotiationPolicy } from '../../types.js';
 import type { ContentNegotiationResolution, NegotiationRouteRule } from './content-negotiation.js';
 import type { MarkdownRequest } from './markdown-request.js';
-/** Marks the internal HTML fetch that the explicit `.md` handler makes. */
+/** Marks an internal HTML fetch that must bypass content negotiation. */
 export declare const INTERNAL_HEADER = "x-ai-ready-internal";
 /**
  * Where the decision runs. The early stage sits in front of the Nitro static

package/dist/runtime/server/utils/runCron.d.ts

@@ -1,6 +1,25 @@
 import type { H3Event } from '#nuxtseo/h3';
 import type { StaleCheckResult } from './checkStale.js';
+/**
+ * Why a run could not finish.
+ *
+ * `lock` means the run never started, so nothing was changed. `run` means it
+ * started and stopped part way, so some work may already be committed.
+ */
+export interface CronFailure {
+    stage: 'lock' | 'run';
+    message: string;
+}
 export interface CronResult {
+    /**
+     * Set when the run failed.
+     *
+     * A scheduled task that throws reaches Cloudflare as `scriptThrewException`,
+     * which carries no stage, no message, and nothing a host can report. The
+     * failure travels back as a value instead, so the caller decides what to do
+     * with it.
+     */
+    failed?: CronFailure;
     runId?: number | null;
     stale?: StaleCheckResult;
     sitemap?: {
@@ -19,6 +38,11 @@ export interface CronResult {
 }
 /**
  * Run cron job logic - shared between scheduled task and HTTP endpoint
+ *
+ * This is the error boundary for the whole run. Nothing throws past it: the
+ * scheduled task has no request context and no handler above it, so a throw
+ * here becomes an opaque platform exception rather than something the host can
+ * report. Every failure comes back as `CronResult.failed`.
  */
 export declare function runCron(event: H3Event | undefined, options?: {
     batchSize?: number;

package/dist/runtime/server/utils/runCron.js

@@ -6,17 +6,34 @@ import { checkAndHandleStale, STALE_CHECK_INTERVAL_MS } from "./checkStale.js";
 import { resolveCronPlan, resolveSitemapIntervalMinutes } from "./cron-plan.js";
 import { crawlSitemapByRoute, getSitemapsFromConfig } from "./sitemap.js";
 import { mapSitemapRoutes } from "./sitemap-routes.js";
+function describeFailure(error) {
+  if (error instanceof Error)
+    return error.message;
+  return String(error);
+}
 export async function runCron(event, options) {
   if (import.meta.dev)
     return {};
+  return executeCron(event, options).catch((error) => {
+    const message = describeFailure(error);
+    logger.error(`[cron] Run failed: ${message}`);
+    return { failed: { stage: "run", message } };
+  });
+}
+async function executeCron(event, options) {
   const config = useRuntimeConfig()["nuxt-ai-ready"];
   const debug = config.debug;
   const startTime = Date.now();
   const results = {};
   const allErrors = [];
   const sitemapIntervalMinutes = resolveSitemapIntervalMinutes(config.runtimeSync.ttl);
-  const acquired = await tryAcquireCronLock(event);
-  if (!acquired) {
+  const lock = await tryAcquireCronLock(event).catch((error) => {
+    logger.error(`[cron] Could not acquire the lock: ${describeFailure(error)}`);
+    return null;
+  });
+  if (lock === null)
+    return { failed: { stage: "lock", message: "Could not acquire the cron lock" } };
+  if (lock._tag === "held") {
     if (debug) {
       logger.info(`[cron] Skipping - another cron run is in progress`);
     }
@@ -122,7 +139,7 @@ export async function runCron(event, options) {
     }
     return results;
   } finally {
-    await releaseCronLock(event).catch((err) => {
+    await releaseCronLock(event, lock.token).catch((err) => {
       logger.warn(`[cron] Failed to release lock: ${err?.message || err}`);
     });
   }
@@ -152,7 +169,7 @@ async function pingSitemap(event, config, sitemapIntervalMinutes, debug) {
     route: nextSitemap.route,
     state: nextSitemap.crawlState
   });
-  const routes = [...mapSitemapRoutes(result.urls).keys()];
+  const routes = [...mapSitemapRoutes(result.urls).entries()].map(([route, url]) => ({ route, url: url.loc }));
   if (routes.length > 0)
     await seedRoutes(event, routes);
   if (result._tag === "failed") {

package/dist/runtime/server/utils/sitemap-md.d.ts

@@ -0,0 +1,13 @@
+export declare const SITEMAP_MD_ROUTE = "/sitemap.md";
+export interface SitemapMdEntry {
+    route: string;
+    title?: string;
+    updatedAt?: string;
+}
+export interface SitemapMdOptions {
+    siteName?: string;
+    resolveHref?: (route: string) => string;
+}
+export declare function buildSitemapMd(entries: SitemapMdEntry[], options?: SitemapMdOptions): string;
+export declare function appendSitemapSection(markdown: string, sitemapHref?: string): string;
+export declare function isSitemapMdRequest(path: string, baseURL: string, enabled: boolean): boolean;