@raystack/chronicle 0.7.4 → 0.9.0

package/src/server/api/search.ts

@@ -1,79 +1,129 @@
-import MiniSearch from 'minisearch';
 import { defineHandler, HTTPError } from 'nitro';
+import { useDatabase } from 'nitro/database';
 import type { OpenAPIV3 } from 'openapi-types';
 import { getSpecSlug } from '@/lib/api-routes';
 import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
-import { extractFrontmatter, getPagesForVersion } from '@/lib/source';
+import { extractFrontmatter, getPageSearchContent, getPagesForVersion } from '@/lib/source';
 import { LATEST_CONTEXT, type VersionContext } from '@/lib/version-source';
 
 interface SearchDocument {
   id: string;
   url: string;
   title: string;
-  content: string;
+  headings: string;
+  body: string;
   type: 'page' | 'api';
 }
 
-const indexCache = new Map<string, MiniSearch<SearchDocument>>();
-const docsCache = new Map<string, SearchDocument[]>();
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
-function keyFor(ctx: VersionContext): string {
+const LOCK_FILE = path.join(os.tmpdir(), 'chronicle-search-ready');
+
+export const indexedVersions = new Set<string>();
+let indexPromise: Promise<void> | null = null;
+
+function versionKey(ctx: VersionContext): string {
   return ctx.dir ?? '__latest__';
 }
 
-function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
-  const index = new MiniSearch<SearchDocument>({
-    fields: ['title', 'content'],
-    storeFields: ['url', 'title', 'type'],
-    searchOptions: {
-      boost: { title: 2 },
-      fuzzy: 0.2,
-      prefix: true
-    }
-  });
-  index.addAll(docs);
-  return index;
+// biome-ignore lint/suspicious/noEmptyBlockStatements: intentional no-op catch
+fs.unlink(LOCK_FILE).catch(() => {});
+
+export function isSearchReady(): boolean {
+  return existsSync(LOCK_FILE);
+}
+
+export async function ensureIndex(ctx: VersionContext) {
+  const key = versionKey(ctx);
+  if (indexedVersions.has(key)) return;
+  if (indexPromise) return indexPromise;
+  indexPromise = buildIndex(ctx, key);
+  await indexPromise;
+  indexPromise = null;
+  await fs.writeFile(LOCK_FILE, new Date().toISOString());
+}
+
+async function buildIndex(ctx: VersionContext, key: string) {
+  // biome-ignore lint/correctness/useHookAtTopLevel: useDatabase is a Nitro DI accessor, not a React hook
+  const db = useDatabase();
+
+  await db.exec('DROP TABLE IF EXISTS search_fts');
+  await db.exec('DROP TABLE IF EXISTS search_docs');
+
+  await db.exec(`CREATE TABLE IF NOT EXISTS search_docs (
+    id TEXT PRIMARY KEY,
+    url TEXT NOT NULL,
+    title TEXT NOT NULL,
+    headings TEXT NOT NULL,
+    body TEXT NOT NULL,
+    type TEXT NOT NULL,
+    version TEXT NOT NULL
+  )`);
+
+  await db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
+    title,
+    headings,
+    body,
+    content=search_docs,
+    content_rowid=rowid
+  )`);
+
+  const docs = await buildDocs(ctx);
+  for (const doc of docs) {
+    await db.sql`INSERT INTO search_docs (id, url, title, headings, body, type, version)
+      VALUES (${doc.id}, ${doc.url}, ${doc.title}, ${doc.headings}, ${doc.body}, ${doc.type}, ${key})`;
+  }
+
+  await db.sql`INSERT INTO search_fts (rowid, title, headings, body)
+    SELECT rowid, title, headings, body FROM search_docs WHERE version = ${key}`;
+
+  indexedVersions.add(key);
 }
 
-async function scanContent(ctx: VersionContext): Promise<SearchDocument[]> {
+async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
+  const docs: SearchDocument[] = [];
+
   const pages = await getPagesForVersion(ctx);
-  return pages.map(p => {
+  for (const p of pages) {
     const fm = extractFrontmatter(p);
-    return {
+    const { headings, body } = await getPageSearchContent(p);
+    docs.push({
       id: p.url,
       url: p.url,
       title: fm.title,
-      content: fm.description ?? '',
-      type: 'page' as const
-    };
-  });
-}
+      headings,
+      body: [fm.description ?? '', body].join(' '),
+      type: 'page',
+    });
+  }
 
-async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   const config = loadConfig();
   const apiConfigs = getApiConfigsForVersion(config, ctx.dir);
-  if (!apiConfigs.length) return [];
-
-  const docs: SearchDocument[] = [];
-  const specs = await loadApiSpecs(apiConfigs);
-
-  for (const spec of specs) {
-    const specSlug = getSpecSlug(spec);
-    const paths = spec.document.paths ?? {};
-    for (const [, pathItem] of Object.entries(paths)) {
-      if (!pathItem) continue;
-      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
-        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
-        if (!op?.operationId) continue;
-        const url = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
-        docs.push({
-          id: url,
-          url,
-          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
-          content: op.description ?? '',
-          type: 'api'
-        });
+  if (apiConfigs.length) {
+    const specs = await loadApiSpecs(apiConfigs);
+    for (const spec of specs) {
+      const specSlug = getSpecSlug(spec);
+      const paths = spec.document.paths ?? {};
+      for (const [pathStr, pathItem] of Object.entries(paths)) {
+        if (!pathItem) continue;
+        for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+          const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+          if (!op) continue;
+          const opId = op.operationId ?? `${method}_${pathStr.replace(/[/{}\-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+          const url = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(opId)}`;
+          docs.push({
+            id: url,
+            url,
+            title: `${method.toUpperCase()} ${op.summary ?? opId}`,
+            headings: op.summary ?? opId,
+            body: [op.description ?? '', pathStr, method.toUpperCase()].join(' '),
+            type: 'api',
+          });
+        }
       }
     }
   }
@@ -81,27 +131,32 @@ async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   return docs;
 }
 
-async function getDocs(ctx: VersionContext): Promise<SearchDocument[]> {
-  const key = keyFor(ctx);
-  const cached = docsCache.get(key);
-  if (cached) return cached;
-  const [contentDocs, apiDocs] = await Promise.all([
-    scanContent(ctx),
-    buildApiDocs(ctx)
-  ]);
-  const docs = [...contentDocs, ...apiDocs];
-  docsCache.set(key, docs);
-  return docs;
-}
+function findMatch(
+  query: string,
+  title: string,
+  headings: string,
+  body: string,
+): { match: 'title' | 'heading' | 'body'; snippet: string } {
+  if (title.toLowerCase().includes(query)) {
+    return { match: 'title', snippet: title };
+  }
 
-async function getIndex(ctx: VersionContext): Promise<MiniSearch<SearchDocument>> {
-  const key = keyFor(ctx);
-  const cached = indexCache.get(key);
-  if (cached) return cached;
-  const docs = await getDocs(ctx);
-  const index = createIndex(docs);
-  indexCache.set(key, index);
-  return index;
+  const headingList = headings.split('\n').filter(Boolean);
+  for (const h of headingList) {
+    if (h.toLowerCase().includes(query)) {
+      return { match: 'heading', snippet: h };
+    }
+  }
+
+  const idx = body.toLowerCase().indexOf(query);
+  if (idx >= 0) {
+    const start = Math.max(0, idx - 40);
+    const end = Math.min(body.length, idx + query.length + 80);
+    const snippet = (start > 0 ? '...' : '') + body.slice(start, end).trim() + (end < body.length ? '...' : '');
+    return { match: 'body', snippet };
+  }
+
+  return { match: 'title', snippet: title };
 }
 
 function resolveCtx(tag: string | null): VersionContext {
@@ -121,25 +176,44 @@ export default defineHandler(async event => {
   const query = event.url.searchParams.get('query') ?? '';
   const tag = event.url.searchParams.get('tag');
   const ctx = resolveCtx(tag);
-  const index = await getIndex(ctx);
+
+  await ensureIndex(ctx);
+  // biome-ignore lint/correctness/useHookAtTopLevel: useDatabase is a Nitro DI accessor, not a React hook
+  const db = useDatabase();
+  const key = versionKey(ctx);
 
   if (!query) {
-    const docs = await getDocs(ctx);
-    return Response.json(docs
-      .filter(d => d.type === 'page')
-      .slice(0, 8)
-      .map(d => ({
-        id: d.id,
-        url: d.url,
-        type: d.type,
-        content: d.title
-      })));
+    const result = await db.sql`SELECT id, url, title, type FROM search_docs
+      WHERE version = ${key} AND type = 'page'
+      LIMIT 8`;
+    return Response.json((result.rows ?? []).map(r => ({
+      id: r.id,
+      url: r.url,
+      type: r.type,
+      content: r.title,
+    })));
   }
 
-  return Response.json(index.search(query).map(r => ({
-    id: r.id,
-    url: r.url,
-    type: r.type,
-    content: r.title
-  })));
+  const searchTerm = query.split(/\s+/).map(t => `"${t}"*`).join(' ');
+  const result = await db.sql`SELECT s.id, s.url, s.title, s.headings, s.body, s.type,
+      bm25(search_fts, 10.0, 5.0, 1.0) AS score
+    FROM search_fts f
+    JOIN search_docs s ON s.rowid = f.rowid
+    WHERE search_fts MATCH ${searchTerm}
+      AND s.version = ${key}
+    ORDER BY score
+    LIMIT 20`;
+
+  const queryLower = query.toLowerCase();
+  return Response.json((result.rows ?? []).map(r => {
+    const { match, snippet } = findMatch(queryLower, r.title as string, r.headings as string, r.body as string);
+    return {
+      id: r.id,
+      url: r.url,
+      type: r.type,
+      content: r.title,
+      match,
+      snippet,
+    };
+  }));
 });

package/src/server/entry-server.tsx

@@ -19,7 +19,7 @@ import serverAssets from './entry-server?assets=ssr';
 export default {
   async fetch(req: Request) {
     const url = new URL(req.url);
-    const pathname = url.pathname;
+    const pathname = decodeURIComponent(url.pathname);
 
     const config = loadConfig();
     const route = resolveRoute(pathname, config);

package/src/server/routes/[...slug].md.ts

@@ -7,6 +7,7 @@ import { safePath } from '@/server/utils/safe-path';
 export default defineHandler(async event => {
   const pathname = event.path || event.req.url?.split('?')[0] || '';
   if (!pathname.endsWith('.md')) return;
+  if (pathname.startsWith('/apis/')) return;
 
   const stripped = pathname.replace(/\.md$/, '');
   const parts = stripped === '/index' || stripped === '/'

package/src/server/routes/apis/[...slug].md.ts

@@ -0,0 +1,181 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import { defineHandler, HTTPError } from 'nitro'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { findApiOperation } from '@/lib/api-routes'
+import { flattenSchema, generateExampleJson, type SchemaField } from '@/lib/schema'
+import { generateCurl } from '@/lib/snippet-generators'
+
+export default defineHandler(async event => {
+  const pathname = event.path || event.req.url?.split('?')[0] || ''
+  if (!pathname.endsWith('.md')) return
+
+  const stripped = pathname.replace(/\.md$/, '').replace(/^\/apis\//, '')
+  const slug = stripped.split('/').filter(Boolean)
+  if (slug.length < 2) {
+    throw new HTTPError({ status: 404, message: 'Not Found' })
+  }
+
+  const config = loadConfig()
+  const specs = await loadApiSpecs(config.api ?? [])
+  const match = findApiOperation(specs, slug)
+
+  if (!match) {
+    throw new HTTPError({ status: 404, message: 'Not Found' })
+  }
+
+  const md = generateApiMarkdown(match.method, match.path, match.operation, match.spec.server.url, match.spec.auth)
+  return new Response(md, { headers: { 'Content-Type': 'text/markdown; charset=utf-8' } })
+})
+
+function generateApiMarkdown(
+  method: string,
+  path: string,
+  operation: OpenAPIV3.OperationObject,
+  serverUrl: string,
+  auth?: { type: string; header: string; placeholder?: string },
+): string {
+  const lines: string[] = []
+  const params = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[]
+
+  lines.push(`# ${operation.summary ?? `${method} ${path}`}`)
+  lines.push('')
+  if (operation.description) {
+    lines.push(operation.description)
+    lines.push('')
+  }
+  lines.push(`\`${method}\` \`${path}\``)
+  lines.push('')
+
+  const headerParams = params.filter(p => p.in === 'header')
+  const pathParams = params.filter(p => p.in === 'path')
+  const queryParams = params.filter(p => p.in === 'query')
+
+  if (auth || headerParams.length > 0) {
+    lines.push('## Authorization')
+    lines.push('')
+    lines.push('| Header | Type | Required | Description |')
+    lines.push('| --- | --- | --- | --- |')
+    if (auth) {
+      lines.push(`| \`${auth.header}\` | string | Yes | ${auth.placeholder ?? 'API key'} |`)
+    }
+    for (const p of headerParams) {
+      const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+      lines.push(`| \`${p.name}\` | ${schema.type ?? 'string'} | ${p.required ? 'Yes' : 'No'} | ${p.description ?? ''} |`)
+    }
+    lines.push('')
+  }
+
+  if (pathParams.length > 0) {
+    lines.push('## Path Parameters')
+    lines.push('')
+    lines.push('| Parameter | Type | Required | Description |')
+    lines.push('| --- | --- | --- | --- |')
+    for (const p of pathParams) {
+      const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+      lines.push(`| \`${p.name}\` | ${schema.type ?? 'string'} | ${p.required ? 'Yes' : 'No'} | ${p.description ?? ''} |`)
+    }
+    lines.push('')
+  }
+
+  if (queryParams.length > 0) {
+    lines.push('## Query Parameters')
+    lines.push('')
+    lines.push('| Parameter | Type | Required | Description |')
+    lines.push('| --- | --- | --- | --- |')
+    for (const p of queryParams) {
+      const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+      lines.push(`| \`${p.name}\` | ${schema.type ?? 'string'} | ${p.required ? 'Yes' : 'No'} | ${p.description ?? ''} |`)
+    }
+    lines.push('')
+  }
+
+  const requestBody = operation.requestBody as OpenAPIV3.RequestBodyObject | undefined
+  if (requestBody?.content) {
+    const contentType = Object.keys(requestBody.content)[0]
+    const schema = contentType ? requestBody.content[contentType]?.schema as OpenAPIV3.SchemaObject : undefined
+    if (schema) {
+      lines.push('## Request Body')
+      lines.push('')
+      lines.push(`Content-Type: \`${contentType}\``)
+      lines.push('')
+      const fields = flattenSchema(schema)
+      if (fields.length > 0) {
+        lines.push('| Field | Type | Required | Description |')
+        lines.push('| --- | --- | --- | --- |')
+        renderFieldTable(fields, lines, 0)
+        lines.push('')
+      }
+      const example = generateExampleJson(schema)
+      lines.push('**Example:**')
+      lines.push('')
+      lines.push('```json')
+      lines.push(JSON.stringify(example, null, 2))
+      lines.push('```')
+      lines.push('')
+    }
+  }
+
+  const responses = operation.responses as Record<string, OpenAPIV3.ResponseObject> | undefined
+  if (responses) {
+    lines.push('## Responses')
+    lines.push('')
+    for (const [status, resp] of Object.entries(responses)) {
+      lines.push(`### ${status}${resp.description ? ` — ${resp.description}` : ''}`)
+      lines.push('')
+      const content = resp.content ?? {}
+      const contentType = Object.keys(content)[0]
+      const schema = contentType ? content[contentType]?.schema as OpenAPIV3.SchemaObject : undefined
+      if (schema) {
+        const fields = flattenSchema(schema)
+        if (fields.length > 0) {
+          lines.push('| Field | Type | Description |')
+          lines.push('| --- | --- | --- |')
+          renderResponseFieldTable(fields, lines, 0)
+          lines.push('')
+        }
+        const example = generateExampleJson(schema)
+        lines.push('```json')
+        lines.push(JSON.stringify(example, null, 2))
+        lines.push('```')
+        lines.push('')
+      }
+    }
+  }
+
+  const headers: Record<string, string> = {}
+  if (auth) headers[auth.header] = auth.placeholder ?? 'YOUR_API_KEY'
+  if (requestBody?.content) {
+    const ct = Object.keys(requestBody.content)[0]
+    if (ct) headers['Content-Type'] = ct
+  }
+
+  const bodySchema = requestBody?.content
+    ? (Object.values(requestBody.content)[0]?.schema as OpenAPIV3.SchemaObject | undefined)
+    : undefined
+  const bodyStr = bodySchema ? JSON.stringify(generateExampleJson(bodySchema), null, 2) : undefined
+
+  lines.push('## cURL')
+  lines.push('')
+  lines.push('```bash')
+  lines.push(generateCurl({ method, url: serverUrl + path, headers, body: bodyStr }))
+  lines.push('```')
+
+  return lines.join('\n')
+}
+
+function renderFieldTable(fields: SchemaField[], lines: string[], depth: number) {
+  const indent = '  '.repeat(depth)
+  for (const f of fields) {
+    lines.push(`| ${indent}\`${f.name}\` | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description ?? ''} |`)
+    if (f.children) renderFieldTable(f.children, lines, depth + 1)
+  }
+}
+
+function renderResponseFieldTable(fields: SchemaField[], lines: string[], depth: number) {
+  const indent = '  '.repeat(depth)
+  for (const f of fields) {
+    lines.push(`| ${indent}\`${f.name}\` | ${f.type} | ${f.description ?? ''} |`)
+    if (f.children) renderResponseFieldTable(f.children, lines, depth + 1)
+  }
+}

package/src/server/vite-config.ts

@@ -48,6 +48,7 @@ export async function createViteConfig(
 
   return {
     root: packageRoot,
+    publicDir: path.resolve(projectRoot, 'public'),
     configFile: false,
     plugins: [
       nitro({
@@ -131,9 +132,19 @@ export async function createViteConfig(
     },
     nitro: {
       logLevel: 2,
+      publicAssets: [{ dir: path.resolve(projectRoot, 'public') }],
       output: {
         dir: resolveOutputDir(projectRoot, preset),
       },
+      experimental: {
+        database: true,
+      },
+      database: {
+        default: {
+          connector: 'sqlite',
+          options: { name: 'chronicle-search' },
+        },
+      },
     },
   };
 }

package/src/themes/default/Layout.module.css

@@ -226,3 +226,56 @@
 .page {
   padding: var(--rs-space-2) 0;
 }
+
+.apiGroup {
+  margin-top: var(--rs-space-8);
+  width: 100%;
+}
+
+.apiGroup:first-child {
+  margin-top: 0;
+}
+
+.apiGroupLabel {
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  color: var(--rs-color-foreground-base-secondary);
+  padding: 0 var(--rs-space-3);
+}
+
+.apiItem {
+  padding: var(--rs-space-3);
+  border-radius: var(--rs-radius-2);
+  text-decoration: none;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.apiItem:hover {
+  background: var(--rs-color-background-neutral-secondary);
+}
+
+.apiItemActive {
+  background: var(--rs-color-background-neutral-secondary);
+}
+
+.apiItemName {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.apiMethodText {
+  font-family: var(--rs-font-mono);
+  font-size: var(--rs-font-size-mono-mini);
+  line-height: var(--rs-line-height-mini);
+  flex-shrink: 0;
+}