nuxt-ai-ready 1.3.8 → 1.4.0

package/dist/devtools/lib/ai-ready/rpc.ts

@@ -0,0 +1,6 @@
+import { useDevtoolsConnection } from 'nuxtseo-layer-devtools/composables/rpc'
+
+// The layer owns host fetch + route tracking and refreshes on connect; ai-ready's
+// state.ts watches refreshTime to reload the global debug data, so no module-level
+// host access is needed here.
+useDevtoolsConnection()

package/dist/devtools/lib/ai-ready/state.ts

@@ -0,0 +1,21 @@
+import type { DevtoolsGlobalData } from './types'
+import { appFetch } from 'nuxtseo-layer-devtools/composables/rpc'
+import { productionUrl, refreshTime } from 'nuxtseo-layer-devtools/composables/state'
+import { ref, watch } from 'vue'
+
+export const data = ref<DevtoolsGlobalData | null>(null)
+export const loading = ref(true)
+
+export async function refreshSources() {
+  if (!appFetch.value || typeof appFetch.value !== 'function')
+    return
+  data.value = await appFetch.value('/__ai-ready__/debug.json', { responseType: 'json' }).catch(() => null)
+  loading.value = false
+  if (data.value?.siteConfigUrl)
+    productionUrl.value = data.value.siteConfigUrl
+}
+
+// Re-fetch the global debug data when the host connection or manual refresh changes
+watch([appFetch, refreshTime], () => {
+  refreshSources()
+})

package/dist/devtools/lib/ai-ready/types.ts

@@ -0,0 +1,50 @@
+export interface DevtoolsConfig {
+  database: { type: string }
+  runtimeSync: { enabled: boolean, ttl: number, batchSize: number, pruneTtl: number }
+  indexNow: boolean
+  sitemapPrerendered: boolean
+  markdownCacheHeaders: { maxAge: number, swr: boolean }
+  llmsTxtCacheSeconds: number
+  contentSignal: false | { aiTrain: boolean, search: boolean, aiInput: boolean }
+  mcp: { enabled: boolean, tools: boolean, resources: boolean }
+  cron: boolean
+}
+
+export interface LlmsTxtLink {
+  title: string
+  description?: string
+  href: string
+}
+
+export interface LlmsTxtSection {
+  title: string
+  description?: string | string[]
+  links?: LlmsTxtLink[]
+}
+
+export interface LlmsTxtConfig {
+  sections?: LlmsTxtSection[]
+  notes?: string | string[]
+}
+
+export interface PageSummary {
+  route: string
+  title: string
+  description: string
+  updatedAt: string | null
+}
+
+export interface DevtoolsGlobalData {
+  version: string
+  siteConfigUrl: string
+  isDev: boolean
+  config: DevtoolsConfig
+  llmsTxt: LlmsTxtConfig
+  stats?: {
+    total: number
+    indexed: number
+    pending: number
+    errors: number
+  }
+  pages?: PageSummary[]
+}

package/dist/devtools/nuxt.config.ts

@@ -0,0 +1,3 @@
+// Nuxt SEO devtools panel, shipped as a layer (Model C). The unified devtools client
+// (assembled by nuxtseo-shared in the user's project) extends this to render /ai-ready.
+export default defineNuxtConfig({})

package/dist/devtools/pages/ai-ready/debug.vue

@@ -0,0 +1,27 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+import { data } from '../../lib/ai-ready/state'
+
+const config = computed(() => data.value?.config)
+const llmsTxt = computed(() => data.value?.llmsTxt)
+
+const configJson = computed(() => config.value ? JSON.stringify(config.value, null, 2) : '')
+const llmsTxtJson = computed(() => llmsTxt.value ? JSON.stringify(llmsTxt.value, null, 2) : '')
+const fullJson = computed(() => data.value ? JSON.stringify(data.value, null, 2) : '')
+</script>
+
+<template>
+  <div class="space-y-4">
+    <DevtoolsSection text="Module Config" icon="carbon:settings" :open="true">
+      <DevtoolsSnippet v-if="configJson" :code="configJson" lang="json" />
+    </DevtoolsSection>
+
+    <DevtoolsSection text="llms.txt Config" icon="carbon:document" :open="true">
+      <DevtoolsSnippet v-if="llmsTxtJson" :code="llmsTxtJson" lang="json" />
+    </DevtoolsSection>
+
+    <DevtoolsSection text="Full Response" icon="carbon:code" :open="false">
+      <DevtoolsSnippet v-if="fullJson" :code="fullJson" lang="json" />
+    </DevtoolsSection>
+  </div>
+</template>

package/dist/devtools/pages/ai-ready/docs.vue

@@ -0,0 +1,3 @@
+<template>
+  <DevtoolsDocs url="https://nuxtseo.com/ai-ready" />
+</template>

package/dist/devtools/pages/ai-ready/index.vue

@@ -0,0 +1,177 @@
+<script lang="ts" setup>
+import { appFetch } from 'nuxtseo-layer-devtools/composables/rpc'
+import { hasProductionUrl, isProductionMode, previewSource } from 'nuxtseo-layer-devtools/composables/state'
+import { computed, ref } from 'vue'
+import { useAsyncData } from '#imports'
+import { data as globalData } from '../../lib/ai-ready/state'
+
+const isDev = computed(() => globalData?.value?.isDev ?? true)
+const stats = computed(() => globalData?.value?.stats)
+const pages = computed(() => globalData?.value?.pages || [])
+
+const search = ref('')
+const selectedRoute = ref<string | null>(null)
+
+const filteredPages = computed(() => {
+  if (!search.value)
+    return pages.value
+  const q = search.value.toLowerCase()
+  return pages.value.filter(p =>
+    p.route.toLowerCase().includes(q)
+    || p.title?.toLowerCase().includes(q)
+    || p.description?.toLowerCase().includes(q),
+  )
+})
+
+// Fetch markdown for selected page
+const { data: markdownContent, status: mdStatus } = useAsyncData('page-markdown', async () => {
+  if (!appFetch.value || !selectedRoute.value)
+    return null
+  try {
+    const mdRoute = selectedRoute.value === '/' ? '/index.md' : `${selectedRoute.value}.md`
+    return await appFetch.value(mdRoute, { responseType: 'text' }) as string
+  }
+  catch {
+    return null
+  }
+}, {
+  watch: [selectedRoute, appFetch],
+})
+</script>
+
+<template>
+  <div class="space-y-4">
+    <!-- Dev mode empty state -->
+    <template v-if="isDev && !isProductionMode">
+      <DevtoolsEmptyState
+        icon="carbon:list"
+        title="No pages in development"
+        description="Pages are indexed during prerendering or via runtime sync. The database is empty in dev mode."
+      >
+        <div class="mt-4 space-y-2">
+          <button
+            v-if="hasProductionUrl"
+            type="button"
+            class="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md bg-[var(--seo-green)] text-white hover:opacity-90 transition-opacity cursor-pointer"
+            @click="previewSource = 'production'"
+          >
+            <UIcon name="carbon:cloud" class="w-3.5 h-3.5" />
+            Switch to Production
+          </button>
+          <p class="text-xs text-[var(--color-text-muted)]">
+            Or run <code class="px-1 py-0.5 rounded bg-[var(--color-surface-elevated)]">nuxi generate</code> to populate page data.
+          </p>
+        </div>
+      </DevtoolsEmptyState>
+    </template>
+
+    <!-- Page browser (production mode or has pages) -->
+    <template v-else>
+      <!-- Stats -->
+      <div v-if="stats" class="grid grid-cols-2 sm:grid-cols-4 gap-3">
+        <DevtoolsMetric
+          label="Total Pages"
+          :value="stats.total"
+          icon="carbon:document-multiple"
+        />
+        <DevtoolsMetric
+          label="Indexed"
+          :value="stats.indexed"
+          icon="carbon:checkmark-filled"
+          variant="success"
+        />
+        <DevtoolsMetric
+          label="Pending"
+          :value="stats.pending"
+          icon="carbon:time"
+          :variant="stats.pending > 0 ? 'warning' : 'default'"
+        />
+        <DevtoolsMetric
+          label="Errors"
+          :value="stats.errors"
+          icon="carbon:warning-alt"
+          :variant="stats.errors > 0 ? 'danger' : 'default'"
+        />
+      </div>
+
+      <!-- Search -->
+      <div class="flex items-center gap-2">
+        <div class="relative flex-1">
+          <UIcon name="carbon:search" class="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-[var(--color-text-muted)]" />
+          <input
+            v-model="search"
+            type="text"
+            placeholder="Search pages..."
+            class="w-full pl-9 pr-3 py-2 text-sm rounded-lg bg-[var(--color-surface-sunken)] border border-[var(--color-border)] text-[var(--color-text)] placeholder:text-[var(--color-text-muted)] outline-none focus:border-[var(--seo-green)] transition-colors"
+          >
+        </div>
+        <span class="text-xs text-[var(--color-text-muted)] shrink-0">
+          {{ filteredPages.length }} page{{ filteredPages.length === 1 ? '' : 's' }}
+        </span>
+      </div>
+
+      <!-- Page list -->
+      <div v-if="filteredPages.length" class="space-y-1">
+        <button
+          v-for="page in filteredPages"
+          :key="page.route"
+          type="button"
+          class="w-full text-left p-3 rounded-lg border transition-all cursor-pointer"
+          :class="selectedRoute === page.route
+            ? 'bg-[var(--color-surface-elevated)] border-[var(--seo-green)]'
+            : 'bg-[var(--color-surface)] border-[var(--color-border)] hover:bg-[var(--color-surface-elevated)]'"
+          @click="selectedRoute = selectedRoute === page.route ? null : page.route"
+        >
+          <div class="flex items-start justify-between gap-2">
+            <div class="min-w-0">
+              <div class="text-xs font-mono text-[var(--seo-green)] truncate">
+                {{ page.route }}
+              </div>
+              <div v-if="page.title" class="text-sm font-medium text-[var(--color-text)] truncate mt-0.5">
+                {{ page.title }}
+              </div>
+              <div v-if="page.description" class="text-xs text-[var(--color-text-muted)] line-clamp-2 mt-0.5">
+                {{ page.description }}
+              </div>
+            </div>
+            <div v-if="page.updatedAt" class="text-[10px] text-[var(--color-text-subtle)] shrink-0">
+              {{ new Date(page.updatedAt).toLocaleDateString() }}
+            </div>
+          </div>
+        </button>
+      </div>
+
+      <DevtoolsEmptyState
+        v-else-if="search"
+        icon="carbon:search"
+        title="No matching pages"
+        :description="`No pages match &quot;${search}&quot;`"
+      />
+
+      <DevtoolsEmptyState
+        v-else
+        icon="carbon:list"
+        title="No pages indexed"
+        description="The production site has no indexed pages yet. Ensure prerendering has run."
+      />
+
+      <!-- Markdown preview panel -->
+      <DevtoolsPanel
+        v-if="selectedRoute"
+        :title="`${selectedRoute}.md`"
+        icon="carbon:document"
+      >
+        <div v-if="mdStatus === 'pending'" class="py-4">
+          <DevtoolsLoading />
+        </div>
+        <div v-else-if="markdownContent" class="relative">
+          <DevtoolsCopyButton :text="markdownContent" class="absolute top-2 right-2 z-10" />
+          <pre class="text-xs font-mono whitespace-pre-wrap p-4 rounded-lg bg-[var(--color-surface-sunken)] text-[var(--color-text)] overflow-auto max-h-[500px]">{{ markdownContent }}</pre>
+        </div>
+        <p v-else class="text-xs text-[var(--color-text-muted)] p-4">
+          Could not load markdown for this route.
+        </p>
+      </DevtoolsPanel>
+    </template>
+  </div>
+</template>

package/dist/devtools/pages/ai-ready/llms-txt.vue

@@ -0,0 +1,172 @@
+<script lang="ts" setup>
+import { appFetch } from 'nuxtseo-layer-devtools/composables/rpc'
+import { isProductionMode, refreshTime } from 'nuxtseo-layer-devtools/composables/state'
+import { computed, ref } from 'vue'
+import { useAsyncData } from '#imports'
+import { data as globalData } from '../../lib/ai-ready/state'
+
+const isDev = computed(() => globalData?.value?.isDev ?? true)
+const llmsTxtConfig = computed(() => globalData?.value?.llmsTxt)
+
+const activeTab = ref<'llms-txt' | 'llms-full'>('llms-txt')
+
+// Fetch actual llms.txt content
+const { data: llmsTxtContent } = useAsyncData('llms-txt-content', async () => {
+  if (!appFetch.value)
+    return null
+  try {
+    return await appFetch.value('/llms.txt', { responseType: 'text' }) as string
+  }
+  catch {
+    return null
+  }
+}, {
+  watch: [appFetch, refreshTime],
+})
+
+const { data: llmsFullContent, status: fullStatus } = useAsyncData('llms-full-content', async () => {
+  if (!appFetch.value || activeTab.value !== 'llms-full')
+    return null
+  try {
+    return await appFetch.value('/llms-full.txt', { responseType: 'text' }) as string
+  }
+  catch {
+    return null
+  }
+}, {
+  watch: [appFetch, refreshTime, activeTab],
+})
+
+const displayContent = computed(() => {
+  if (activeTab.value === 'llms-full')
+    return llmsFullContent.value
+  return llmsTxtContent.value
+})
+
+// Build a template preview from config (for dev mode)
+const templatePreview = computed(() => {
+  const config = llmsTxtConfig.value
+  if (!config)
+    return ''
+
+  const lines: string[] = ['# {Site Name}', '', '> {Site Description}', '']
+
+  for (const section of config.sections || []) {
+    lines.push(`## ${section.title}`)
+    if (section.description) {
+      const descs = Array.isArray(section.description) ? section.description : [section.description]
+      for (const d of descs)
+        lines.push('', d)
+    }
+    for (const link of section.links || []) {
+      const desc = link.description ? `: ${link.description}` : ''
+      lines.push(`- [${link.title}](${link.href})${desc}`)
+    }
+    lines.push('')
+  }
+
+  if (config.notes) {
+    const notes = Array.isArray(config.notes) ? config.notes : [config.notes]
+    for (const note of notes)
+      lines.push(note)
+  }
+
+  return lines.join('\n')
+})
+</script>
+
+<template>
+  <div class="space-y-4">
+    <!-- Tab switcher -->
+    <div class="flex items-center gap-2">
+      <button
+        v-for="tab in [{ key: 'llms-txt', label: 'llms.txt' }, { key: 'llms-full', label: 'llms-full.txt' }]"
+        :key="tab.key"
+        type="button"
+        class="px-3 py-1.5 text-xs font-medium rounded-md transition-all cursor-pointer"
+        :class="activeTab === tab.key
+          ? 'bg-[var(--seo-green)] text-white'
+          : 'bg-[var(--color-surface-elevated)] text-[var(--color-text-muted)] hover:text-[var(--color-text)]'"
+        @click="activeTab = tab.key as any"
+      >
+        {{ tab.label }}
+      </button>
+    </div>
+
+    <!-- Dev mode: template preview hint -->
+    <DevtoolsAlert
+      v-if="isDev && !isProductionMode"
+      variant="info"
+    >
+      <p class="font-medium mb-1">
+        Template Preview
+      </p>
+      <p class="text-sm opacity-80">
+        This shows the llms.txt structure from your config. Actual content with page data is generated during prerendering.
+        Switch to production mode to see live content.
+      </p>
+    </DevtoolsAlert>
+
+    <!-- Content display -->
+    <DevtoolsPanel :title="activeTab === 'llms-txt' ? 'llms.txt' : 'llms-full.txt'">
+      <!-- Loading state for llms-full.txt -->
+      <div v-if="activeTab === 'llms-full' && fullStatus === 'pending'" class="py-8 text-center">
+        <DevtoolsLoading />
+      </div>
+
+      <!-- Show content or template -->
+      <template v-else>
+        <div v-if="displayContent" class="relative">
+          <DevtoolsCopyButton :text="displayContent" class="absolute top-2 right-2 z-10" />
+          <pre class="text-xs font-mono whitespace-pre-wrap p-4 rounded-lg bg-[var(--color-surface-sunken)] text-[var(--color-text)] overflow-auto max-h-[600px]">{{ displayContent }}</pre>
+        </div>
+
+        <!-- Fallback: show template preview in dev -->
+        <div v-else-if="isDev && templatePreview" class="relative">
+          <pre class="text-xs font-mono whitespace-pre-wrap p-4 rounded-lg bg-[var(--color-surface-sunken)] text-[var(--color-text-muted)] overflow-auto max-h-[600px]">{{ templatePreview }}</pre>
+        </div>
+
+        <DevtoolsEmptyState
+          v-else
+          icon="carbon:document"
+          title="No content available"
+          description="llms.txt content is generated during prerendering. Run `nuxi generate` or switch to production mode."
+        />
+      </template>
+    </DevtoolsPanel>
+
+    <!-- llms.txt Structure (always visible) -->
+    <DevtoolsSection text="Configured Sections" icon="carbon:list-boxes">
+      <div v-if="llmsTxtConfig?.sections?.length" class="space-y-3">
+        <div
+          v-for="(section, i) in llmsTxtConfig.sections"
+          :key="i"
+          class="p-3 rounded-lg bg-[var(--color-surface-elevated)] border border-[var(--color-border)]"
+        >
+          <h4 class="text-sm font-semibold text-[var(--color-text)] mb-1">
+            {{ section.title }}
+          </h4>
+          <div v-if="section.links?.length" class="space-y-1 mt-2">
+            <div
+              v-for="(link, j) in section.links"
+              :key="j"
+              class="flex items-start gap-2 text-xs"
+            >
+              <UIcon name="carbon:link" class="w-3 h-3 mt-0.5 text-[var(--color-text-muted)]" />
+              <div>
+                <span class="font-medium text-[var(--color-text)]">{{ link.title }}</span>
+                <span v-if="link.description" class="text-[var(--color-text-muted)]">, {{ link.description }}</span>
+                <div class="font-mono text-[var(--color-text-subtle)]">
+                  {{ link.href }}
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+      <p v-else class="text-xs text-[var(--color-text-muted)]">
+        No custom sections configured.
+      </p>
+    </DevtoolsSection>
+  </div>
+</template>

package/dist/devtools/pages/ai-ready.vue

@@ -0,0 +1,50 @@
+<script lang="ts" setup>
+import { isProductionMode } from 'nuxtseo-layer-devtools/composables/state'
+import { computed, watch } from 'vue'
+import { navigateTo, useRoute } from '#imports'
+import { data, loading, refreshSources } from '../lib/ai-ready/state'
+import '../lib/ai-ready/rpc'
+
+const route = useRoute()
+const currentTab = computed(() => {
+  const path = route.path
+  if (path === '/ai-ready/llms-txt')
+    return 'llms-txt'
+  if (path === '/ai-ready/debug')
+    return 'debug'
+  if (path === '/ai-ready/docs')
+    return 'docs'
+  return 'pages'
+})
+
+const navItems = [
+  { value: 'pages', to: '/ai-ready', icon: 'carbon:list', label: 'Pages', devOnly: false },
+  { value: 'llms-txt', to: '/ai-ready/llms-txt', icon: 'carbon:document', label: 'llms.txt', devOnly: false },
+  { value: 'debug', to: '/ai-ready/debug', icon: 'carbon:debug', label: 'Debug', devOnly: true },
+  { value: 'docs', to: '/ai-ready/docs', icon: 'carbon:book', label: 'Docs', devOnly: false },
+]
+
+const runtimeVersion = computed(() => data.value?.version || 'unknown')
+
+// Debug data is dev-only; leave the debug tab when the header switches to Production
+watch(isProductionMode, (isProd) => {
+  if (isProd && currentTab.value === 'debug')
+    return navigateTo('/ai-ready')
+})
+</script>
+
+<template>
+  <DevtoolsLayout
+    module-name="nuxt-ai-ready"
+    title="AI Ready"
+    icon="carbon:bot"
+    :version="runtimeVersion"
+    :nav-items="navItems"
+    github-url="https://github.com/harlan-zw/nuxt-ai-ready"
+    :loading="loading"
+    :active-tab="currentTab"
+    @refresh="refreshSources"
+  >
+    <NuxtPage />
+  </DevtoolsLayout>
+</template>

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": ">=4.0.0"
   },
   "configKey": "aiReady",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -957,7 +957,7 @@ export async function lookupContentPage(event, path) {
     });
     addServerHandler({ route: "/llms.txt", handler: resolve("./runtime/server/routes/llms.txt.get") });
     addServerHandler({ route: "/llms-full.txt", handler: resolve("./runtime/server/routes/llms-full.txt.get") });
-    addServerHandler({ route: "/__ai-ready/devtools", handler: resolve("./runtime/server/routes/__ai-ready/devtools.get") });
+    addServerHandler({ route: "/__ai-ready__/debug.json", handler: resolve("./runtime/server/routes/__ai-ready/devtools.get") });
     if (config.debug) {
       addServerHandler({ route: "/__ai-ready-debug", handler: resolve("./runtime/server/routes/__ai-ready-debug.get") });
     }

package/dist/runtime/llms-txt-utils.js

@@ -2,6 +2,7 @@ import { useRuntimeConfig } from "nitropack/runtime";
 import { getSiteConfig } from "#site-config/server/composables/getSiteConfig";
 import { normalizeLlmsTxtConfig } from "./llms-txt-format.js";
 import { queryPages } from "./server/db/queries.js";
+import { logger } from "./server/logger.js";
 import { localePath, resolveLocaleFromRoute } from "./server/utils/i18n.js";
 import { fetchSitemapUrls } from "./server/utils/sitemap.js";
 export { normalizeLlmsTxtConfig };
@@ -141,11 +142,21 @@ Canonical Origin: ${siteConfig.url}`);
     parts.push(normalizedContent);
     parts.push("");
   }
-  const [pages, errorPages, urls] = await Promise.all([
-    queryPages(event),
-    queryPages(event, { where: { hasError: true } }),
-    fetchSitemapUrls(event)
-  ]);
+  const urlsPromise = fetchSitemapUrls(event);
+  let pages = [];
+  let errorPages = [];
+  try {
+    ;
+    [pages, errorPages] = await Promise.all([
+      queryPages(event),
+      queryPages(event, { where: { hasError: true } })
+    ]);
+  } catch (err) {
+    logger.warn(
+      `[ai-ready] Database unavailable for llms.txt, falling back to sitemap-only pages: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const urls = await urlsPromise;
   const seenPaths = /* @__PURE__ */ new Set();
   const errorSet = new Set(errorPages.map((p) => p.route));
   const prerendered = [];

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

@@ -1,23 +1,14 @@
-import { mkdir } from "node:fs/promises";
 import { Database } from "bun:sqlite";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 import { useRuntimeConfig } from "nitropack/runtime";
-import { dirname } from "pathe";
 import * as schema from "#ai-ready-virtual/db-schema.mjs";
 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 = config.database.filename || ".data/ai-ready/pages.db";
+  const dbPath = await resolveWritableDbPath(config.database.filename || ".data/ai-ready/pages.db");
   logger.debug(`[drizzle] Opening Bun SQLite database: ${dbPath}`);
-  await mkdir(dirname(dbPath), { recursive: true }).catch((err) => {
-    if (err.code === "EROFS" || err.code === "EACCES") {
-      throw new Error(
-        `[ai-ready] Cannot create database directory (read-only filesystem). On Vercel, set database.type: 'neon'. On Cloudflare, use 'd1'. Or configure database.url for LibSQL/Turso.`
-      );
-    }
-    throw err;
-  });
   const sqlite = new Database(dbPath);
   const db = drizzle(sqlite, { schema });
   registerDriver(db, "better-sqlite3", sqlite);

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

@@ -0,0 +1,14 @@
+/**
+ * Resolve a writable path for a file-based SQLite database, returning the path
+ * to actually open.
+ *
+ * On a read-only filesystem (read-only Docker container, serverless bundle) the
+ * configured directory cannot be written. Rather than crash every request, fall
+ * back to a temp dir so runtime indexing keeps working. The fallback is
+ * namespaced by a hash of the absolute configured path so unrelated apps sharing
+ * the OS temp dir do not open the same SQLite file (the tables are package-global
+ * and not namespaced per site). The fallback database is ephemeral and reseeded
+ * from the prerendered dump / sitemap on cold start, so this is a safe
+ * degradation for the SSR indexing model.
+ */
+export declare function resolveWritableDbPath(dbPath: string): Promise<string>;

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

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "pathe";
+import { logger } from "../../../logger.js";
+const resolved = /* @__PURE__ */ new Map();
+async function ensureWritableDir(dir) {
+  const mkErr = await mkdir(dir, { recursive: true }).then(() => null).catch((e) => e);
+  if (mkErr)
+    return mkErr;
+  const probe = join(dir, ".ai-ready-write-test");
+  const writeErr = await writeFile(probe, "").then(() => null).catch((e) => e);
+  if (writeErr)
+    return writeErr;
+  await rm(probe, { force: true }).catch(() => null);
+  return null;
+}
+function isReadOnly(err) {
+  return err.code === "EROFS" || err.code === "EACCES";
+}
+export async function resolveWritableDbPath(dbPath) {
+  const cached = resolved.get(dbPath);
+  if (cached)
+    return cached;
+  const dir = dirname(dbPath);
+  const err = await ensureWritableDir(dir);
+  if (!err) {
+    resolved.set(dbPath, dbPath);
+    return dbPath;
+  }
+  if (!isReadOnly(err))
+    throw err;
+  const key = createHash("sha256").update(resolve(dbPath)).digest("hex").slice(0, 16);
+  const fallbackDir = join(tmpdir(), `ai-ready-${key}`);
+  const fallbackErr = await ensureWritableDir(fallbackDir);
+  if (fallbackErr) {
+    throw new Error(
+      `[ai-ready] Database directory '${dir}' is read-only and the temp dir fallback ('${fallbackDir}') also failed: ${fallbackErr.message}. Set database.filename to a writable path, or use a serverless driver: database.type 'd1' (Cloudflare), 'neon' (Vercel/Postgres), or 'libsql' (Turso).`
+    );
+  }
+  const fallback = join(fallbackDir, "pages.db");
+  logger.warn(
+    `[ai-ready] Database directory '${dir}' is read-only; falling back to '${fallback}'. This database is ephemeral and reseeded on cold start. Set database.filename to a writable persistent path (or a volume) to silence this warning.`
+  );
+  resolved.set(dbPath, fallback);
+  return fallback;
+}