nuxt-ai-ready 2.5.2 → 3.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "2.5.2",
+  "version": "3.0.0",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",
@@ -24,7 +24,8 @@
   "exports": {
     ".": {
       "types": "./dist/types.d.mts",
-      "import": "./dist/module.mjs"
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
     },
     "./mcp": {
       "types": "./mcp.d.ts",
@@ -45,10 +46,14 @@
     "skills",
     "webmcp.d.ts"
   ],
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  },
   "peerDependencies": {
     "@libsql/client": "^0.18.0",
     "@neondatabase/serverless": "^1.0.0",
-    "better-sqlite3": "^11.0.0 || ^12.0.0 || ^13.0.0",
+    "drizzle-orm": "^1.0.0-rc.4",
+    "nuxt": "^4.6.0 || ^5.0.0",
     "postgres": "^3.4.9"
   },
   "peerDependenciesMeta": {
@@ -58,7 +63,7 @@
     "@neondatabase/serverless": {
       "optional": true
     },
-    "better-sqlite3": {
+    "drizzle-orm": {
       "optional": true
     },
     "postgres": {
@@ -66,27 +71,87 @@
     }
   },
   "dependencies": {
-    "@mdream/js": "2.0.0-beta.1",
-    "@nuxt/kit": "^4.5.2",
-    "@nuxtjs/robots": "^6.2.3",
-    "@nuxtjs/sitemap": "^8.5.1",
+    "@mdream/js": "^2.0.1",
+    "@nuxt/kit": "^4.6.0",
+    "@nuxtjs/robots": "^7.0.0",
+    "@nuxtjs/sitemap": "^9.0.0",
     "citty": "^0.2.2",
+    "confbox": "^0.3.1",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
-    "drizzle-orm": "1.0.0-rc.4",
-    "mdream": "2.0.0-beta.1",
-    "nuxt-site-config": "^4.2.3",
-    "nuxtseo-shared": "^5.3.16",
+    "mdream": "^2.0.1",
+    "nuxt-site-config": "^5.0.0",
+    "nuxtseo-shared": "^6.0.0",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.3",
-    "site-config-stack": "^4.2.3",
+    "site-config-stack": "^5.0.0",
     "sitemapd": "^0.2.2",
     "ufo": "^1.6.4",
-    "uncrypto": "^0.1.3",
     "yaml": "^2.9.1"
   },
-  "bundledDependencies": [
-    "mdream",
-    "@mdream/js"
-  ]
-}
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.5.1",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@harlan-zw/comark-content": "^0.2.0",
+    "@libsql/client": "^0.18.0",
+    "@nuxt/content": "^3.16.1",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/test-utils": "^4.3.3",
+    "@nuxtjs/eslint-config-typescript": "^12.1.0",
+    "@nuxtjs/mcp-toolkit": "^0.23.0",
+    "@types/better-sqlite3": "^9.6.0",
+    "@vitest/coverage-v8": "^5.0.3",
+    "@vue/test-utils": "^2.5.1",
+    "@vueuse/nuxt": "^15.0.0",
+    "better-sqlite3": "^13.0.3",
+    "bumpp": "^12.3.0",
+    "drizzle-orm": "1.0.0-rc.4",
+    "eslint": "^10.12.0",
+    "eslint-plugin-harlanzw": "^0.23.0",
+    "execa": "^10.0.1",
+    "h3": "^2.0.1",
+    "happy-dom": "^20.14.5",
+    "nitropack": "^2.13.4",
+    "nuxt": "4.6.0",
+    "nuxt-site-config": "^5.0.0",
+    "nuxtseo-layer-devtools": "^5.3.16",
+    "playwright": "^1.63.0",
+    "playwright-core": "^1.63.0",
+    "postgres": "^3.4.9",
+    "typescript": "6.0.3",
+    "unbuild": "^3.6.1",
+    "vitest": "^5.0.3",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1",
+    "vue-tsc": "^3.3.12",
+    "wrangler": "^4.147.0",
+    "zod": "^4.6.5"
+  },
+  "build": {
+    "externals": [
+      "node:sqlite",
+      "nuxt/server"
+    ]
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && pnpm run build:devtools && pnpm run test:dist",
+    "build:devtools": "node -e \"require('fs').cpSync('devtools','dist/devtools',{recursive:true})\"",
+    "dev": "nuxt dev playground",
+    "dev:minimal": "nuxt dev playground",
+    "prepare:fixtures": "nuxt prepare playground && nuxt prepare playground && nuxt prepare test/fixtures/basic",
+    "dev:build": "nuxt build playground",
+    "dev:build:minimal": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && nuxt prepare playground && pnpm run build:devtools",
+    "dev:prepare:minimal": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && nuxt prepare playground",
+    "release": "pnpm build && bumpp -x \"npx changelogen --output=CHANGELOG.md\"",
+    "test": "vitest run && pnpm test:nuxt5",
+    "test:run": "pnpm run prepare:fixtures && vitest run && pnpm test:nuxt5",
+    "test:unit": "vitest run --project=unit",
+    "test:e2e": "pnpm run prepare:fixtures && vitest run --project=e2e",
+    "test:dist": "node scripts/check-dist-imports.mjs",
+    "typecheck": "nuxt typecheck && tsc -p test/types/tsconfig.json",
+    "test:attw": "attw --pack",
+    "test:nuxt5": "pnpm build && pnpm --dir test/fixtures/nuxt5 install --frozen-lockfile && pnpm --dir test/fixtures/nuxt5 test"
+  }
+}

package/skills/nuxt-ai-ready/SKILL.md

@@ -1,24 +1,30 @@
 ---
 name: nuxt-ai-ready
-description: Add, configure, or debug AI and LLM discoverability in a Nuxt site with the nuxt-ai-ready module. Use when a task mentions llms.txt, llms-full.txt, serving pages as Markdown (.md routes, Accept text/markdown), an MCP server for site content, WebMCP or useWebMcpTool, Content Signals in robots.txt, agent skills discovery, runtime page indexing, queryPages or searchPages, or the aiReady config key. Gives the automatic outputs, the build versus runtime split, and the traps that leave output empty or stale.
+description: Add, configure, or debug AI and LLM discoverability in a Nuxt site with the nuxt-ai-ready module. Use when a task mentions llms.txt, llms-full.txt, serving pages as Markdown (.md routes, Accept text/markdown), an MCP server for site content, WebMCP or useWebMcpTool, Content Signals in robots.txt, agent skills discovery, runtime page indexing, queryPages or searchPages, or the aiReady config key.
+license: MIT
+compatibility: "Requires Node.js ^22.22.3 || ^24.15.0 || >=26.0.0. Requires Nuxt ^4.6.0 || ^5.0.0."
 ---
 
 # nuxt-ai-ready
 
-Tested against `nuxt-ai-ready` 2.4.1 plus its unreleased fixes on `main`, on Nuxt 4.5 and Node 24 (requires Nuxt `>=4.0.0`).
+Covers `nuxt-ai-ready` v3 on Nuxt 4.6 or Nuxt 5.
 The module converts rendered pages to Markdown with mdream and publishes `llms.txt`, `llms-full.txt`, and `.md` twins.
 Optional parts add MCP tools, WebMCP tools, and a runtime page index. Config key: `aiReady`. Docs: https://nuxtseo.com/ai-ready
 
 ## Setup
 
+Included in `@nuxtjs/seo` v6. If the app uses `@nuxtjs/seo`, configure the `aiReady` key and do not add the module again.
+Nuxt SEO uses AI Ready's own defaults. It overrides no `aiReady` option.
+With these defaults the database stays off, so the app does not need `drizzle-orm`.
+
 The package installs `@nuxtjs/robots` and `@nuxtjs/sitemap` and loads them as module dependencies. Configure them with the `robots` and `sitemap` keys.
 
 ```bash
-pnpm add nuxt-ai-ready
+npx nuxt module add nuxt-ai-ready
 ```
 
 Set `site.url`. Canonical URLs, `Link` headers, and `/.well-known/ai-catalog.json` use it.
-Prerender the pages you want in `llms-full.txt` and in the page index (`nuxi generate`, or `nitro.prerender.routes`).
+Prerender the pages you want in `llms-full.txt` and in the page index (`nuxt generate`, or `nitro.prerender.routes`).
 A page visit in dev or production does not index anything.
 
 ## Automatic behaviour
@@ -28,11 +34,11 @@ With no `aiReady` config, the module adds:
 - `/llms.txt`: site name, description, resource links, and a `## Pages` list. In dev it lists sitemap routes without titles.
 - `/llms-full.txt`: the full Markdown of each prerendered page. Only prerendered pages go in the static file.
 - A `.md` twin per page. `/about` becomes `/about.md`, and `/` becomes `/index.md`. Paths under `/api` and `/_` get none.
-- Accept negotiation: a request that prefers `text/markdown`, or a known AI bot user agent, gets a `307` to the `.md` URL.
+- Accept negotiation: a request that prefers `text/markdown` gets a `307` to the `.md` URL. Responses send `Vary: Accept`. AI bot user agents get Markdown only with `botNegotiation: true`.
 - `<link rel="alternate" type="text/markdown">` and `<link rel="describedby" href="/llms.txt">` in HTML, plus matching `Link` headers.
 - `/sitemap.md`, and a `## Sitemap` footer on every generated `.md` page. Set `sitemapMd: false` to remove both.
 - Nuxt Content v3 `page` collections: the `.md` route serves the source Markdown, not converted HTML. Set `contentSource: false` to convert HTML.
-- Agent skills: every `skills/<name>/SKILL.md` in the project root or a local layer is published at `/.well-known/agent-skills/`, at `/skills/<name>/SKILL.md`, and in `llms.txt`. With one skill it is also served at `/SKILL.md`. Set `agentSkills: false` to publish nothing.
+- Agent skills: `public/skills/<name>/SKILL.md` in the project or a local layer is published at `/.well-known/agent-skills/`, `/skills/<name>/SKILL.md`, and in `llms.txt`. Custom public directories are supported. One local skill is also served at `/SKILL.md`. Set `agentSkills: false` to publish nothing.
 
 Off by default: Content Signals, MCP, WebMCP, runtime sync, cron, and the database.
 
@@ -77,9 +83,9 @@ export default defineNuxtConfig({ aiReady: { contentSignal: { search: true } } }
 // robots.txt: Content-Signal: ai-train=no, search=yes, ai-input=no
 ```
 
-MCP: install `@nuxtjs/mcp-toolkit` and add it to `modules`. The module then registers `list_pages`, `search_pages`, and `get_page_markdown` at `/mcp`. MCP needs a running server; `nuxi generate` output cannot host it.
+MCP: install `@nuxtjs/mcp-toolkit` and add it to `modules`. The module then registers `list_pages`, `search_pages`, and `get_page_markdown` at `/mcp`. These tools need the database, so also run `npx nypm add drizzle-orm@1.0.0-rc.4`. MCP needs a running server; `nuxt generate` output cannot host it.
 
-WebMCP: set `webmcp: true`. This registers the same three tools in the browser and auto-imports `useWebMcpTool()` and `useWebMcpSupported()`. Without `webmcp`, those composables are not defined.
+WebMCP: set `webmcp: true`. This registers the same three tools in the browser and auto-imports `useWebMcpTool()` and `useWebMcpSupported()`. The tools need the database and `drizzle-orm`. Without `webmcp`, those composables are not defined.
 
 Runtime indexing, database drivers, Cloudflare D1, and the server query helpers: see [references/runtime-indexing.md](references/runtime-indexing.md).
 
@@ -87,15 +93,23 @@ Runtime indexing, database drivers, Cloudflare D1, and the server query helpers:
 
 - **The same edit in both hooks applies twice.** During prerendering the Nitro `ai-ready:page:markdown` hook runs, then the Nuxt hook of the same name. Put an edit in one of them, not both.
 - **Content source pages skip conversion hooks.** A Nuxt Content page ignores `mdreamOptions` and both Nitro hooks.
-- **Dev has no page data.** Query helpers, MCP tools, and search return empty results in `nuxi dev`. Test with `nuxi build` and `node .output/server/index.mjs`.
-- **Response caching turns negotiation off.** An ISR, `swr`, or `cache` route rule without `varies: ['accept', 'sec-fetch-dest', 'user-agent']` serves HTML to Markdown clients. The `.md` URL still works. For a CDN that caches by URL only, set `contentNegotiation: false`.
+- **Dev has no page data.** Query helpers, MCP tools, and search return empty results in `nuxt dev`. Test with `nuxt build` and `node .output/server/index.mjs`.
+- **Response caching turns negotiation off.** An ISR, `swr`, or `cache` route rule without `varies: ['accept']` serves HTML to Markdown clients. With `botNegotiation: true`, the rule needs `varies: ['accept', 'sec-fetch-dest', 'user-agent']`. The `.md` URL still works. For a CDN that caches by URL only, set `contentNegotiation: false`.
 - **Emptying `ctx.markdown` does not hide a page.** It drops the body from `llms-full.txt`. The URL stays in `llms.txt` and in the index. Use `sitemap.exclude` for discovery, and access control for private pages.
-- **A project `skills/` folder is public.** Agent skills discovery publishes it with no opt in. Rename the folder with `agentSkills.dir`, or set `agentSkills: false`.
+- **Root `skills/` folders require explicit publication.** Automatic discovery scans public directories only. Set `agentSkills.dir: 'skills'` to publish root skills intentionally.
 - **The same hook name exists twice.** `ai-ready:page:markdown` is a Nuxt hook (`nuxt.config` `hooks`, prerender only) and a Nitro hook (`nitroApp.hooks`, every HTML conversion). They receive different context. The Nitro `ctx.event` is undefined when indexing runs outside a request.
 - **`database: false` conflicts with `runtimeSync` and `cron`.** The build fails and names the option.
+- **A database feature without `drizzle-orm` fails the build.** `runtimeSync`, `cron`, MCP site tools, WebMCP site tools, and an explicit `database` option turn on the database. The error names the feature and the install command. If MCP Toolkit serves only your own tools, set `database: false` instead.
 
 ## Version limits
 
+- v3 requires Nuxt `^4.6.0 || ^5.0.0` and Node `^22.22.3 || ^24.15.0 || >=26.0.0`. Upgrade Nuxt before the module.
+- v3 does not install `drizzle-orm`. It is an optional peer. If a feature uses the database, run `npx nypm add drizzle-orm@1.0.0-rc.4`.
+- v3 removed the `better-sqlite3` fallback. SQLite uses `node:sqlite`. Remove `better-sqlite3` if only this module used it.
+- v3 negotiates on `Accept` only. To serve Markdown to AI bot user agents again, set `botNegotiation: true` and vary caches on `accept`, `sec-fetch-dest`, and `user-agent`.
+- v3 discovers skills in `public/skills/<name>/SKILL.md` by default. Root `skills/` stays private. Move public skills, or set `agentSkills.dir: 'skills'`.
+- v3 needs `@nuxtjs/robots` v7, `@nuxtjs/sitemap` v9, and `nuxt-site-config` v5. Upgrade direct dependencies on them.
+- v3 adds typed entries. Import server functions from `#ai-ready/server` and app functions from `#ai-ready/app`.
 - v2 removed IndexNow. The `indexNow` option and `/__ai-ready/indexnow` no longer exist. Submit URLs from the `ai-ready:page:indexed` Nitro hook: https://nuxtseo.com/docs/ai-ready/advanced/indexnow
 - v1 renamed these. Do not write the old form:
 
@@ -120,4 +134,4 @@ Runtime indexing, database drivers, Cloudflare D1, and the server query helpers:
 
 - `curl -H 'Accept: text/markdown' -D - -o /dev/null <url>` must return `307` with `Location: <path>.md`. A `200` means a cache rule turned negotiation off.
 - `/__ai-ready__/debug.json` exists in dev, or with `debug: true`.
-- Nuxt DevTools has an AI Ready tab.
+- Nuxt DevTools has an AI Ready tab. The panel needs `nuxtseo-devtools-host` as a dev dependency.

package/skills/nuxt-ai-ready/references/runtime-indexing.md

@@ -6,17 +6,18 @@ If each deployment prerenders all content, you do not need runtime sync.
 ## When the database is on
 
 The database stays off until a feature needs it: `runtimeSync`, `cron`, MCP page tools, WebMCP page tools, or an explicit `database` config.
+Every driver needs the optional `drizzle-orm` peer. Install it with `npx nypm add drizzle-orm@1.0.0-rc.4`. Without it, the build fails and names the feature.
 Prerendering always writes a temporary SQLite index and a dump at `/__ai-ready/pages.dump`.
 
-Driver selection:
+Driver selection. The Install column lists what the driver needs in addition to `drizzle-orm`. Each package is an optional peer, so the app installs it:
 
 | Platform | Driver | Install |
 |----------|--------|---------|
-| Node 22.13 and later | `node:sqlite` | nothing |
-| Node before 22.13 | `better-sqlite3` | `better-sqlite3`, or the build fails |
+| Node.js | `node:sqlite` | nothing |
 | Bun | `bun:sqlite` | nothing |
 | Cloudflare preset | D1 | a binding |
-| Vercel with `POSTGRES_URL` | Neon | nothing |
+| Vercel with `POSTGRES_URL` | Neon | `@neondatabase/serverless` |
+| `database: { type: 'libsql' }` | LibSQL | `@libsql/client` |
 | `database: { type: 'postgres' }` | PostgreSQL | `postgres` |
 
 The build machine always uses SQLite, also for a D1 deployment.
@@ -54,7 +55,7 @@ Traps:
 
 ## Server query helpers
 
-`queryPages`, `searchPages`, `countPages`, `streamPages`, `indexPage`, and `indexPageByRoute` are auto-imported in Nitro code. Other exports need `import { ... } from '#ai-ready'`.
+`queryPages`, `searchPages`, `countPages`, `streamPages`, `indexPage`, and `indexPageByRoute` are auto-imported in Nitro code. Other exports need `import { ... } from '#ai-ready/server'`.
 
 ```ts
 // server/api/search.get.ts
@@ -68,7 +69,7 @@ export default defineEventHandler(async (event) => {
 
 - `searchPages` returns `[]` in dev and during prerender. On SQLite and D1, `score` is BM25 and lower ranks first. PostgreSQL returns `score: 0`.
 - `queryPages(event, { route })` returns one page or `undefined`. Without `route` it returns an array. Add `includeMarkdown: true` for the body.
-- Raw SQL: `useRawDb` from `#ai-ready`. `useDatabase` does not exist.
+- Raw SQL: `useRawDb` from `#ai-ready/server`. `useDatabase` does not exist.
 - The event goes in a different position: `indexPage(route, html, options, event)` and `indexPageByRoute(route, event, options)`.
 - `indexPage` throws on failure. `indexPageByRoute` returns `{ success: false, error }`.
 

package/dist/runtime/server/db/drizzle/providers/sqlite.d.ts

@@ -1,8 +0,0 @@
-import type { H3Event } from '#nuxtseo/h3';
-import Database from 'better-sqlite3';
-export declare function createClient(event?: H3Event): Promise<{
-    dialect: "sqlite";
-    db: import("drizzle-orm/better-sqlite3").BetterSQLite3Database<import("drizzle-orm").EmptyRelations> & {
-        $client: Database.Database;
-    };
-}>;

package/dist/runtime/server/db/drizzle/providers/sqlite.js

@@ -1,15 +0,0 @@
-import Database from "better-sqlite3";
-import { drizzle } from "drizzle-orm/better-sqlite3";
-import { useRuntimeConfig } from "#nuxtseo/nitro";
-import { logger } from "../../../logger.js";
-import { registerDriver } from "../raw.js";
-import { resolveWritableDbPath } from "./dbPath.js";
-export async function createClient(event) {
-  const config = useRuntimeConfig(event)["nuxt-ai-ready"];
-  const dbPath = await resolveWritableDbPath(config.database.filename || ".data/ai-ready/pages.db");
-  logger.debug(`[drizzle] Opening SQLite database: ${dbPath}`);
-  const sqlite = new Database(dbPath);
-  const db = drizzle({ client: sqlite });
-  registerDriver(db, "better-sqlite3", sqlite);
-  return { dialect: "sqlite", db };
-}

package/node_modules/@mdream/js/LICENSE.md

@@ -1,9 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Harlan Wilton
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.